# Agent prompts

> Read the prompts an agent runs on, find why it said something, change a prompt from your tools, compare two versions and restore an earlier one.

Source: https://docs.whatsetter.com/developers/guides/prompts/

An agent runs on a few texts: how it replies, its first message and its follow-ups. The API reads them exactly as the agent uses them, changes them, and keeps the history. In the API an agent is called a campaign.

## Endpoints

| Method | Path | Scope |
|---|---|---|
| GET | [`/campaigns/{id}/prompts`](/api-reference/operations/getcampaignprompts/) | `prompts:read` |
| GET | [`/campaigns/{id}/prompts/{type}`](/api-reference/operations/getcampaignprompt/) | `prompts:read` |
| PUT | [`/campaigns/{id}/prompts/{type}`](/api-reference/operations/updatecampaignprompt/) | `prompts:write` |
| GET | [`/campaigns/{id}/prompts/{type}/versions`](/api-reference/operations/listpromptversions/) | `prompts:read` |
| GET | [`/campaigns/{id}/prompts/{type}/versions/{versionId}`](/api-reference/operations/getpromptversion/) | `prompts:read` |
| GET | [`/campaigns/{id}/prompts/{type}/versions/{versionId}/compare`](/api-reference/operations/comparepromptversions/) | `prompts:read` |
| POST | [`/campaigns/{id}/prompts/{type}/versions/{versionId}/restore`](/api-reference/operations/restorepromptversion/) | `prompts:write` |

`{id}` is the campaign `id` or its `campaign_id`, both from `GET /campaigns`. `{type}` is one of these:

| `type` | In the dashboard | History |
|---|---|---|
| `conversation` | **Conversation**: how the agent replies | Versions |
| `first_message` | **First message** | Versions |
| `follow_up_cold_1`, `follow_up_cold_2` | **Follow-ups** to a lead who never replied | None |
| `follow_up_abandoned_1`, `follow_up_abandoned_2` | **Follow-ups** to a lead who stopped replying | None |
| `group_reply`, `group_dm` | The two texts of a group agent | None |

A private-message agent has the first six. A group agent has the last two. Asking an agent for a text it does not have answers `409 invalid_state`.

## Read what an agent runs on

One call returns every text of the agent, the values of its variables and the knowledge base it answers from.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data } = await res.json();
const conversation = data.prompts.find((p) => p.type === 'conversation');
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts",
    headers={"Authorization": "Bearer ws_live_…"},
)
data = r.json()["data"]
conversation = next(p for p in data["prompts"] if p["type"] == "conversation")
```

```json
{
  "data": {
    "campaign": { "id": "66f1a2b3c4d5e6f7a8b9c0c1", "campaign_id": "acme-france-1-ab12", "name": "Acme France", "agent_name": "Julien", "status": "active", "purpose": "setter" },
    "prompts": [
      {
        "type": "conversation",
        "versioned": true,
        "ab_test": false,
        "live": [
          {
            "variant": "A",
            "name": null,
            "version": 7,
            "version_id": "68e60d3100212c0a9b41",
            "traffic_share": 1,
            "created_at": "2026-10-07T09:18:22.000+00:00",
            "body": "## Identity\nYou are {{agent_name}} from {{company_name}}.\n\n## Goal\nQualify the lead, then send {{goal_link}}.",
            "characters": 109
          }
        ],
        "unpublished_drafts": [],
        "max_characters": 40000
      },
      {
        "type": "follow_up_cold_1",
        "versioned": false,
        "body": "Write a short follow-up to {{prospectName}} who has not replied yet.",
        "uses_default": false,
        "characters": 68,
        "max_characters": 15000,
        "enabled": true,
        "delay_hours": 24
      }
    ],
    "variables": {
      "agent_name": "Julien",
      "company_name": "Acme France",
      "goal_link": "https://cal.com/acme/demo",
      "language": "English"
    },
    "knowledge_base_id": "68c1f1c4001a09be5d10"
  }
}
```

| Field | Meaning |
|---|---|
| `prompts[].live` | What the agent reads right now. One entry, or one per variant while an A/B test runs. |
| `live[].version` | The version number. `null` only when the text in service is in no version: it is then live on its own. |
| `live[].traffic_share` | Share of new conversations this variant gets. `1` when it is alone. |
| `unpublished_drafts` | Texts saved in the dashboard and never published, which the agent does not read. See [When a draft waits](#when-a-draft-waits). |
| `enabled`, `delay_hours` | Follow-ups only: whether it is sent, and after how many hours of silence. |
| `uses_default` | `true` when the agent has no text of its own there and uses the built-in one. `body` is then `null`. |
| `variables` | The value behind each token of the texts, your own variables included. |
| `knowledge_base_id` | The base the agent answers from. See [Knowledge bases](/developers/guides/knowledge/). |

Tokens are written with double curly braces, like `{{agent_name}}`. They are resolved for each message. `{{first_name}}` and `{{lead:<column>}}` are filled per lead, so they are not in `variables`. Add `?rendered=true` to also get `rendered_body`: each live text with its variables resolved and the agent's style inlined.

## What is live

**Live** means what the agent reads on its next message, by the same rule as the agent itself:

- A text published with **Publish** in the dashboard, or written through this API, is live.
- A text saved without publishing is a draft. The agent does not read it. It is listed in `unpublished_drafts` for as long as it is the newest text of its variant and differs from what the agent reads.
- While an A/B test runs, several variants are live at once. Each message of a conversation says which variant wrote it: see `variant` in [Conversations](/developers/guides/conversations/).

The live text is a numbered version. One case is different: a text in service that is in no version. It is then live on its own, with `version` and `version_id` at `null`. The first change made through the API files it in the history before replacing it.

## Change a prompt

Send the full text, not a diff. Read it first, change what you need, keep the tokens and the section headings as they are.

**cURL**

```bash
curl -X PUT "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "## Identity\nYou are {{agent_name}} from {{company_name}}.\n\n## Goal\nQualify the lead, then send {{goal_link}}.\n\n## Rules\nNever give a price before the lead says what they need.",
    "if_version": 7
  }'
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation',
  {
    method: 'PUT',
    headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' },
    body: JSON.stringify({ body: newText, if_version: 7 }),
  },
);
const { data } = await res.json();
console.log(data.changed, data.version, data.previous_version_id);
```

**Python**

```python
import requests

r = requests.put(
    "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation",
    headers={"Authorization": "Bearer ws_live_…"},
    json={"body": new_text, "if_version": 7},
)
data = r.json()["data"]
print(data["changed"], data["version"], data["previous_version_id"])
```

```json
{
  "data": {
    "changed": true,
    "type": "conversation",
    "variant": "A",
    "version": 8,
    "version_id": "68e61f7700093d5b1c02",
    "previous_version": 7,
    "previous_version_id": "68e60d3100212c0a9b41",
    "unknown_tokens": [],
    "prompt": { "type": "conversation", "versioned": true, "ab_test": false, "live": [ { "variant": "A", "version": 8, "…": "…" } ], "unpublished_drafts": [], "max_characters": 40000 }
  }
}
```

| Field | Rules |
|---|---|
| `body` | Required. The full text. Up to 40000 characters for `conversation` and `group_reply`, 25000 for `first_message` and `group_dm`, 15000 for a follow-up. |
| `if_version` | Optional. The live version you read (`0` when the live text has no version). If the text changed since, the call answers `409 version_conflict` and writes nothing. |
| `variant` | Only while an A/B test runs: `A`, `B`, `C` or `D`, the variant you change. Its share of the traffic is kept. |
| `ignore_draft` | Optional. `true` to publish although a draft waits on this text. See [When a draft waits](#when-a-draft-waits). |

> **The change is live at once**
A prompt written through the API is used on the agent's next message, on an active agent too. It is the same as **Publish** in the dashboard. Keep `previous_version_id` from the answer: it is your way back.

Four more things to know:

- Sending the text that is already live writes nothing and answers `changed: false`.
- The answer lists `unknown_tokens`: the tokens of your text that match no variable of the agent. They are not resolved, so the agent would read them as they stand. Correct them and send the text again.
- Starting, stopping or rebalancing an A/B test stays in the dashboard, and so do the variables themselves.
- When the text in service was in no version, it is filed in the history first, as a version marked `snapshot`. `previous_version_id` names it, so the change can be undone like any other.

## When a draft waits

A draft is a text saved in the dashboard and never published. Its author sees it in the editor, and the agent does not read it. While a draft waits on a text, a write to that text answers `409 draft_pending` and writes nothing: publishing another text would leave the draft aside without anyone choosing to.

```json
{
  "error": {
    "code": "draft_pending",
    "message": "Version 9 of this text (id 68e7a1c2000f3b7a2d15) was saved in the dashboard on 2026-10-09 and never published: the agent does not read it, and it differs from the text in service. Publishing now would leave that draft aside. Compare it with the text in service (GET …/versions/{id}/compare), then either publish it (POST …/versions/{id}/restore) or send this request again with \"ignore_draft\": true: the draft then stays in the history, unpublished."
  }
}
```

The draft is named in `unpublished_drafts`, with its `version_id`. Two calls settle it:

1. **See what it changes.** `GET …/versions/{versionId}/compare` with the draft's id compares it with the text in service.
2. **Choose.** To publish the draft, restore it: `POST …/versions/{versionId}/restore`. To keep the text in service as your base, send your write again with `"ignore_draft": true`.

A draft left aside is not deleted. It stays in the history with the status `draft`, and it leaves `unpublished_drafts` because a newer version is live.

## Follow-ups and group agents

These texts keep no history. A write replaces the text, and the answer carries `previous_body`, the text it replaced. Store it if you may want it back. `variant` and `if_version` do not apply.

```json
{
  "data": {
    "changed": true,
    "type": "follow_up_cold_1",
    "previous_body": "Write a short follow-up to {{prospectName}} who has not replied yet.",
    "unknown_tokens": [],
    "prompt": { "type": "follow_up_cold_1", "versioned": false, "body": "Ask one simple question about their project.", "uses_default": false, "characters": 44, "max_characters": 15000, "enabled": true, "delay_hours": 24 }
  }
}
```

Writing a follow-up does not switch it on. `enabled` and `delay_hours` are set in the dashboard, under **Follow-ups**.

## History and restore

`conversation` and `first_message` keep every version. The list is newest first and carries a preview. One version gives its full text.

```bash
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions?limit=10" \
  -H "Authorization: Bearer ws_live_…"
```

```json
{
  "data": [
    { "id": "68e61f7700093d5b1c02", "version": 8, "variant": "A", "name": null, "status": "live", "author": "api", "snapshot": false, "created_at": "2026-10-08T14:02:11.000+00:00", "characters": 175, "preview": "## Identity You are {{agent_name}} from {{company_name}}." },
    { "id": "68e60d3100212c0a9b41", "version": 7, "variant": "A", "name": null, "status": "inactive", "author": "dashboard", "snapshot": false, "created_at": "2026-10-07T09:18:22.000+00:00", "characters": 109, "preview": "## Identity You are {{agent_name}} from {{company_name}}." }
  ],
  "pagination": { "has_more": false, "next_cursor": "68e60d3100212c0a9b41" }
}
```

| `status` | Meaning |
|---|---|
| `live` | What the agent reads now. |
| `draft` | Saved in the dashboard, never published. |
| `inactive` | Replaced by a later version, or its variant is out of the test. |

`author` is `api` for a version written with an API key and `dashboard` for the others.

`snapshot` is `true` on a version the API filed itself: the text that was in service outside the history, kept the moment a change replaced it. Its `created_at` is the date of that change, not the day the text was written.

`name` is the name a person gave the variant when publishing. A date written by the dashboard is not a name: it comes back as `null`, and the date is in `created_at`.

To go back, restore a version: pass the `previous_version_id` of a write to undo it. The version is published again as a new version with the same text, to the character, so the history stays a straight line and the restore can itself be undone. Restoring a draft publishes it. Restoring another version while a draft waits answers `409 draft_pending`, unless the body carries `"ignore_draft": true`. Like a write, a restore takes `"if_version"`, the live version you read of the variant this version belongs to (the variant matters for an agent in an A/B test): if that text changed since, it answers `409 version_conflict` and nothing is replaced.

```bash
curl -X POST "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions/68e60d3100212c0a9b41/restore" \
  -H "Authorization: Bearer ws_live_…"
```

## Compare two versions

`GET …/versions/{versionId}/compare` returns what a version changes compared to another one, line by line. Name the other one in `against`. Without `against`, the version is compared to the text in service.

```bash
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions/68e61f7700093d5b1c02/compare?against=68e60d3100212c0a9b41" \
  -H "Authorization: Bearer ws_live_…"
```

```json
{
  "data": {
    "version": { "id": "68e61f7700093d5b1c02", "version": 8, "variant": "A", "status": "live", "created_at": "2026-10-08T14:02:11.000+00:00", "characters": 175 },
    "against": { "id": "68e60d3100212c0a9b41", "version": 7, "variant": "A", "status": "inactive", "created_at": "2026-10-07T09:18:22.000+00:00", "characters": 109 },
    "identical": false,
    "lines_added": 3,
    "lines_removed": 0,
    "diff": "@@ -4,2 +4,5 @@\n ## Goal\n Qualify the lead, then send {{goal_link}}.\n+\n+## Rules\n+Never give a price before the lead says what they need."
  }
}
```

| Field | Meaning |
|---|---|
| `version`, `against` | The two texts compared. `id` and `version` are `null` for a text in service that is in no version. |
| `identical` | `true` when both texts are the same. Line ends and trailing blanks are not differences. |
| `lines_added`, `lines_removed` | The lines the version has and `against` does not, and the reverse. |
| `diff` | A unified diff with two lines of context. A line that starts with `+` is in the version and not in `against`. A line that starts with `-` is the reverse. Empty when `identical` is `true`. |

Three questions it answers:

- **What did a write change?** Compare the new `version_id` against `previous_version_id`.
- **What would a draft change?** Compare the draft's id, without `against`.
- **What changed since an older version?** Compare the live `version_id` against the older one.

## Find why an agent said something

Three reads answer the question "why did my agent say that":

1. **The exchange.** `GET /conversations/{leadId}/messages` gives each message with its `type`. A `LEAD_WELCOME` was written from `first_message`, an `AI_RESPONSE` from `conversation`, a `FOLLOWUP` from a follow-up. A `MANUAL_RESPONSE` was written by a person.
2. **The prompt.** `GET /campaigns/{id}/prompts` for the lead's `campaign_id`. Look for the instruction that led to the message. If the message is older than the live version, the versions list tells you what was live that day. To see what changed between two versions, see [Compare two versions](#compare-two-versions).
3. **The knowledge.** For a reply, `GET /knowledge-bases/{id}/search` with the lead's message returns the passages the agent was handed. See [Knowledge bases](/developers/guides/knowledge/).

With the [MCP server](/developers/mcp/), an assistant does these three reads for you and quotes the sentence that explains the reply.

## Errors you will meet

| HTTP | `code` | When |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Key absent, unknown or revoked. |
| 403 | `insufficient_scope` | The key lacks `prompts:read` or `prompts:write`. A key created before these scopes existed does not have them. |
| 404 | `not_found` | Unknown campaign, type or version, or one of another workspace. |
| 409 | `invalid_state` | The agent has no text of that type, the text keeps no history, or the version to restore holds no text. |
| 409 | `version_conflict` | `if_version` is not the live version: the text changed since you read it. |
| 409 | `draft_pending` | A draft saved in the dashboard waits on the text, and the call does not carry `ignore_draft`. |
| 409 | `variant_required` | An A/B test runs and the call does not name a variant. |
| 409 | `variant_not_live` | The variant named is out of the test while another one serves. |
| 422 | `validation_error` | `body` missing, empty or too long, a `variant` the agent does not have, a bad `if_version`, an `ignore_draft` that is not a boolean. |
| 429 | `rate_limited` | Too many requests this minute. Honor `Retry-After`. |

## Related

- [Knowledge bases](/developers/guides/knowledge/)
- [Conversations](/developers/guides/conversations/)
- [Your agent's prompt in the dashboard](/dashboard/prompt/)
- [MCP server](/developers/mcp/)
