Drafts & Publishing
Conversational Agents are in Beta and available on Professional, Scale and Enterprise.
Every agent has a live configuration (what contacts talk to) and at most one draft. Changes in the agent editor go to the draft. Contacts keep talking to the live configuration until you publish.
Base URL: https://api.sendseven.com/api/v1/automation
| Method | Path | Scope | Success |
|---|---|---|---|
GET | /agents/{agent_id}/draft | automation:read | 200 draft |
GET | /agents/{agent_id}/draft/revision | automation:read | 200 revision only, see Concurrent edits |
PUT | /agents/{agent_id}/draft | automation:update | 200 draft |
DELETE | /agents/{agent_id}/draft | automation:update | 200 draft (now equal to live) |
POST | /agents/{agent_id}/publish | automation:publish (see Who can publish) | 200 agent |
POST | /agents/{agent_id}/avatar | automation:update | 200 draft |
GET | /agents/insights/overview?days=30 | automation:read | 200 — see Insights overview |
PATCH /agents/{agent_id}, PUT /agents/{agent_id}/skills and the knowledge source endpoints still change the live agent immediately, exactly as before. Use them for automation; use the draft endpoints when you want a review step. A pending draft never overwrites those live changes when it is published (see Merge rules).
Publish state
Every agent response carries:
| Field | Notes |
|---|---|
publish_state | published or draft. draft means the agent has never been published, so it does not answer contacts yet. Agents created before drafts existed are published. |
has_unpublished_changes | true while a draft with changes exists. |
draft_updated_at | When the draft was last saved, or null. |
published_at | When the agent was last published, or null. |
POST /agents creates a never-published agent (publish_state: "draft") by default. It answers only in the test console until you publish it. Send "publish": true to put it live on create (needs automation:publish):
{"name": "Shop Support", "instructions": "Answer questions about orders.", "publish": true}
The default of publish on POST /agents changed from true to false. Agents created through the API now start as unpublished drafts. If your integration relied on the old default, send "publish": true explicitly. A never-published agent also does not run from a Flow's Run Assistant step.
is_active and the bot priority are not part of the draft: they always apply instantly.
The draft document
GET /agents/{agent_id}/draft returns:
{
"agent_id": "…",
"bot_id": "…",
"document": {"name": "Shop Support", "instructions": "…", "skills": [], "knowledge_sources": [], "activation_rules": [], "…": "…"},
"live_document": {"…": "…"},
"publish_state": "published",
"has_unpublished_changes": true,
"draft_updated_at": "2026-10-06T09:00:00Z",
"draft_updated_by_name": "Alex Example",
"published_at": "2026-10-01T12:00:00Z",
"published_by_name": "Alex Example",
"revision": 12,
"revision_updated_at": "2026-10-06T09:00:00Z",
"revision_updated_by": {"user_id": "…", "name": "Alex Example"},
"changes": [{"section": "instructions", "fields": ["instructions"]}],
"validation": {"errors": [], "warnings": []},
"avatar_display_url": "https://…",
"widget_connections": [{"widget_id": "…", "name": "Website chat", "widget_type": "live_chat"}]
}
| Field | Notes |
|---|---|
document | The full editable configuration: the draft when one exists, otherwise the live configuration. It accepts the same fields as Create an agent plus name, avatar_url, the greeting button fields, max_credits_per_conversation, skills, knowledge_sources and activation_rules (channels and schedule). |
live_document | The live configuration, only while there are changes (for a side-by-side view). Otherwise null. |
changes | Changed fields grouped by editor section: identity, instructions, skills, knowledge, capabilities, handoff, channels, settings. |
validation.errors | What would block publishing right now (same codes as Publish blockers). |
avatar_display_url | A short-lived URL to show the draft's avatar. Do not store it. |
widget_connections | Active widgets that use this agent directly. Informational. |
revision | A counter that moves whenever the editable configuration changes: draft saves, publish, discard, avatar uploads and live changes through the API. See Concurrent edits. |
revision_updated_at / revision_updated_by | When and by whom the revision last moved. revision_updated_by is null for API-key and system changes. |
Without a draft, GET returns the live configuration with has_unpublished_changes: false. It never creates a draft.
Save the draft
PUT /agents/{agent_id}/draft with {"document": {…}}.
- Send only what you change. Fields you leave out keep their draft (or live) value. An explicit
nullresets a field to its default:max_tool_calls,turn_timeout_ms,model_tierandsource_footer_modecome back as their default value, optional texts are cleared. Anulltoggle, settings section or list keeps its current value. Lists (skills,knowledge_sources,activation_rules) are replaced as a whole when sent. A skill link withoutsourceskeeps its existing per-skill source override. - New list items get a server id. Omit
id(or send any unknown value) on a new knowledge source or activation rule. The response contains the id the server assigned; publishing creates the item with that id. - No change, no draft. If the saved draft ends up identical to the live configuration, the draft is removed and
has_unpublished_changesisfalse. Sending back thedocumentfromGETunchanged is always a no-op. - Unknown fields are rejected (
422). The same checks as the live endpoints apply (skills, tags, KB folders, live source URLs, lookup tables and limits). Where SendSeven can tell which field failed, the422detail also hasfield(the document path, for exampleknowledge_sources.<id>.url) andsection(the editor section); such errors without a code of their own use"code": "invalid_field". A blanknameis allowed in a draft but blocks publishing. avatar_urlcannot be set to a new value here (422 invalid_avatar_url); use the avatar upload. Sending the current value ornull(remove) is fine.- A draft is limited to 1 MB (
422 draft_too_large).
DELETE /agents/{agent_id}/draft throws the draft away and returns the live configuration.
Concurrent edits
Two people (or two browser tabs) can edit the same agent. To avoid silently overwriting each other, send the revision you last saw as base_revision:
| Call | Where base_revision goes |
|---|---|
PUT /agents/{agent_id}/draft | Body: {"document": {…}, "base_revision": 12} |
POST /agents/{agent_id}/publish | Optional body: {"base_revision": 12} |
DELETE /agents/{agent_id}/draft | Query: ?base_revision=12 |
POST /agents/{agent_id}/avatar | Form field base_revision |
If the agent changed since that revision, the call changes nothing and returns 409:
{
"detail": {
"code": "draft_conflict",
"message": "This agent was changed by someone else",
"revision": 13,
"revision_updated_at": "2026-10-06T09:05:00Z",
"revision_updated_by": {"user_id": "…", "name": "Alex Example"},
"current": {"agent_id": "…", "document": {"…": "…"}, "revision": 13, "…": "…"}
}
}
current is the full draft response as it is now. Show it, or save your document again with base_revision set to the new revision to overwrite.
- A save that would not change anything never conflicts and does not move the revision.
- Without
base_revisionthe last write wins, as before. GET /agents/{agent_id}/draft/revisionreturns onlyagent_id,revision,revision_updated_atandrevision_updated_by. It is cheap enough to poll while an editor is open.
Test the draft
POST /agents/{agent_id}/test accepts "config": "draft" to run the turn on the draft instead of the live configuration (default "live"). The response echoes which one ran in config. Without a draft the live configuration is used and config is live. See Test console.
Publish
POST /agents/{agent_id}/publish makes the draft live in one step and returns the updated agent. To see everything that still stands between an agent and going live (blockers, knowledge indexing, channels, flows) in one call, use the readiness check. If there is no draft, it only marks a never-published agent as published.
Who can publish
Putting an agent live (it starts answering customers) needs the automation:publish scope. That covers:
POST /agents/{agent_id}/publishPOST /agentswith"publish": true(the default isfalse)- switching a paused agent on:
PATCH /agents/{agent_id}orPATCH /bots/{bot_id}with"is_active": true - attaching the agent to channels or widgets:
POST /bots/{bot_id}/rulesandPUT /bots/{bot_id}/rules/{rule_id}on the agent's bot
Every caller needs automation:publish: a team member through their role, an OAuth app (for example an MCP client) through its granted scopes, an API token through its own scopes. automation:update alone lets you build and test agents (created as drafts, the default), but you cannot publish them, switch them on or attach them to channels.
Roles, API tokens and app connections that had automation:update when automation:publish was introduced were given automation:publish automatically. New custom roles and tokens get it only when you select it.
A caller without automation:publish can still create agents (as drafts, without "publish": true): they are always created paused (is_active: false), whatever is_active says.
Pausing an agent ("is_active": false), removing a channel rule and editing a live agent need only automation:update. Sending "is_active": true for an agent that is already on is not a publish.
Without the scope, nothing is changed and the response is 403:
{
"detail": {
"code": "agent_publish_not_allowed",
"message": "This app was not granted the automation:publish permission. It can build and test agents; publishing needs that permission.",
"required_scopes": ["automation:publish"]
}
}
Merge rules
The draft remembers the live configuration it started from. On save and on publish, SendSeven combines three versions: that starting point, your draft and the current live configuration.
- A field you changed in the draft wins.
- A field you did not change keeps its current live value, even if someone changed it through the API after the draft was started.
- Settings objects (
tools_config,handoff_config,language_settings, …) are combined key by key. - Lists are combined item by item (skills by
skill_id, sources and rules byid): items you added or removed in the draft are added or removed; items added live in the meantime are kept.
Publish blockers
If the draft cannot go live, nothing is changed and the response is:
{
"detail": {
"code": "publish_blocked",
"message": "The agent cannot be published yet",
"errors": [
{"section": "identity", "field": "ai_disclosure_message", "code": "ai_disclosure_missing"}
]
}
}
code | Meaning |
|---|---|
name_missing | The agent has no name. |
ai_disclosure_missing | The AI notice is set but has no text (only placeholders or spaces). Leave it empty to use the built-in notice. |
live_source_invalid | A live source is incomplete or its URL is not allowed. |
lookup_table_not_found | A lookup-table source points to a table that was deleted. Remove the source or pick another table. |
skill_missing | A linked skill was deleted or archived. |
goal_invalid | A linked skill's goal is invalid. |
handoff_schedule_empty | Hand-off hours are custom with the schedule switched on but no time ranges (section handoff). See Team availability. |
check_unavailable | One of these checks could not run right now (section and field name it). Publishing is blocked rather than skipping the check. Try again in a moment. |
Avatar
POST /agents/{agent_id}/avatar — multipart/form-data with one file. The image goes into the draft; it is shown to contacts after you publish.
- Optional form field
base_revision, see Concurrent edits. - PNG, JPEG or WebP only, max 2 MB. The file content must match its type; SVG is not accepted.
- Errors:
422 {"code": "invalid_avatar", "message": "…"}.
Returns the draft (document.avatar_url and avatar_display_url set).
Insights overview
GET /agents/insights/overview?days=30 — workspace-wide numbers for all agents, or one agent with &agent_id=AGENT_ID. days is 7, 30 (default) or 90; anything else returns 422 invalid_days. Test-console turns are not counted.
{
"range_days": 30,
"goals": [
{"skill_id": "…", "skill_title": "Book a demo", "goal_label": "Collect name, company and preferred date", "started": 42, "completed": 30, "completion_pct": 71.4}
],
"skills_by_usage": [
{"skill_id": "…", "title": "Order returns", "turns": 310, "agents": 2}
],
"kb_gaps": {"pending_count": 5},
"truncated": false
}
| Field | Notes |
|---|---|
goals | Per skill with a goal: goal runs started and completed in the window. completion_pct is null when nothing started. |
skills_by_usage | Replies that used the skill and how many agents used it. |
kb_gaps.pending_count | Knowledge-gap FAQ drafts waiting for review. |
truncated | true when the window had more than 20,000 replies; only the newest were counted. |
Per-agent conversation, hand-off and credit totals are on /hub/stats and /agents/{agent_id}/analytics.