Skip to main content

Drafts & Publishing

Beta

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

MethodPathScopeSuccess
GET/agents/{agent_id}/draftautomation:read200 draft
GET/agents/{agent_id}/draft/revisionautomation:read200 revision only, see Concurrent edits
PUT/agents/{agent_id}/draftautomation:update200 draft
DELETE/agents/{agent_id}/draftautomation:update200 draft (now equal to live)
POST/agents/{agent_id}/publishautomation:publish (see Who can publish)200 agent
POST/agents/{agent_id}/avatarautomation:update200 draft
GET/agents/insights/overview?days=30automation:read200 — see Insights overview
The regular API stays live

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:

FieldNotes
publish_statepublished 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_changestrue while a draft with changes exists.
draft_updated_atWhen the draft was last saved, or null.
published_atWhen 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}
Changed on 16 November 2026

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"}]
}
FieldNotes
documentThe 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_documentThe live configuration, only while there are changes (for a side-by-side view). Otherwise null.
changesChanged fields grouped by editor section: identity, instructions, skills, knowledge, capabilities, handoff, channels, settings.
validation.errorsWhat would block publishing right now (same codes as Publish blockers).
avatar_display_urlA short-lived URL to show the draft's avatar. Do not store it.
widget_connectionsActive widgets that use this agent directly. Informational.
revisionA 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_byWhen 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 null resets a field to its default: max_tool_calls, turn_timeout_ms, model_tier and source_footer_mode come back as their default value, optional texts are cleared. A null toggle, settings section or list keeps its current value. Lists (skills, knowledge_sources, activation_rules) are replaced as a whole when sent. A skill link without sources keeps 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_changes is false. Sending back the document from GET unchanged 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, the 422 detail also has field (the document path, for example knowledge_sources.<id>.url) and section (the editor section); such errors without a code of their own use "code": "invalid_field". A blank name is allowed in a draft but blocks publishing.
  • avatar_url cannot be set to a new value here (422 invalid_avatar_url); use the avatar upload. Sending the current value or null (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:

CallWhere base_revision goes
PUT /agents/{agent_id}/draftBody: {"document": {…}, "base_revision": 12}
POST /agents/{agent_id}/publishOptional body: {"base_revision": 12}
DELETE /agents/{agent_id}/draftQuery: ?base_revision=12
POST /agents/{agent_id}/avatarForm 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_revision the last write wins, as before.
  • GET /agents/{agent_id}/draft/revision returns only agent_id, revision, revision_updated_at and revision_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}/publish
  • POST /agents with "publish": true (the default is false)
  • switching a paused agent on: PATCH /agents/{agent_id} or PATCH /bots/{bot_id} with "is_active": true
  • attaching the agent to channels or widgets: POST /bots/{bot_id}/rules and PUT /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 by id): 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"}
]
}
}
codeMeaning
name_missingThe agent has no name.
ai_disclosure_missingThe AI notice is set but has no text (only placeholders or spaces). Leave it empty to use the built-in notice.
live_source_invalidA live source is incomplete or its URL is not allowed.
lookup_table_not_foundA lookup-table source points to a table that was deleted. Remove the source or pick another table.
skill_missingA linked skill was deleted or archived.
goal_invalidA linked skill's goal is invalid.
handoff_schedule_emptyHand-off hours are custom with the schedule switched on but no time ranges (section handoff). See Team availability.
check_unavailableOne 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
}
FieldNotes
goalsPer skill with a goal: goal runs started and completed in the window. completion_pct is null when nothing started.
skills_by_usageReplies that used the skill and how many agents used it.
kb_gaps.pending_countKnowledge-gap FAQ drafts waiting for review.
truncatedtrue 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.