Guides by resource
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.
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
Section titled “Endpoints”| Method | Path | Scope |
|---|---|---|
| GET | /campaigns/{id}/prompts |
prompts:read |
| GET | /campaigns/{id}/prompts/{type} |
prompts:read |
| PUT | /campaigns/{id}/prompts/{type} |
prompts:write |
| GET | /campaigns/{id}/prompts/{type}/versions |
prompts:read |
| GET | /campaigns/{id}/prompts/{type}/versions/{versionId} |
prompts:read |
| GET | /campaigns/{id}/prompts/{type}/versions/{versionId}/compare |
prompts:read |
| POST | /campaigns/{id}/prompts/{type}/versions/{versionId}/restore |
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
Section titled “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 "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts" \ -H "Authorization: Bearer ws_live_…"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');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"){ "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. |
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. |
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
Section titled “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_draftsfor 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
variantin 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
Section titled “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 -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 }'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);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"]){ "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. |
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_idnames it, so the change can be undone like any other.
When a draft waits
Section titled “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.
{ "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:
- See what it changes.
GET …/versions/{versionId}/comparewith the draft’s id compares it with the text in service. - 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
Section titled “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.
{ "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
Section titled “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.
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions?limit=10" \ -H "Authorization: Bearer ws_live_…"{ "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.
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
Section titled “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.
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions/68e61f7700093d5b1c02/compare?against=68e60d3100212c0a9b41" \ -H "Authorization: Bearer ws_live_…"{ "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_idagainstprevious_version_id. - What would a draft change? Compare the draft’s id, without
against. - What changed since an older version? Compare the live
version_idagainst the older one.
Find why an agent said something
Section titled “Find why an agent said something”Three reads answer the question “why did my agent say that”:
- The exchange.
GET /conversations/{leadId}/messagesgives each message with itstype. ALEAD_WELCOMEwas written fromfirst_message, anAI_RESPONSEfromconversation, aFOLLOWUPfrom a follow-up. AMANUAL_RESPONSEwas written by a person. - The prompt.
GET /campaigns/{id}/promptsfor the lead’scampaign_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. - The knowledge. For a reply,
GET /knowledge-bases/{id}/searchwith the lead’s message returns the passages the agent was handed. See Knowledge bases.
With the MCP server, an assistant does these three reads for you and quotes the sentence that explains the reply.
Errors you will meet
Section titled “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. |