Skip to content
Dashboard

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.

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.

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

Terminal window
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts" \
-H "Authorization: Bearer ws_live_…"
{
"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.

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.

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.

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

Terminal window
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
}'
{
"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_id names it, so the change can be undone like any other.

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:

  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.

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.

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

Terminal window
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.

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

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.

Terminal window
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_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.

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.
  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.

With the MCP server, an assistant does these three reads for you and quotes the sentence that explains the reply.

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.