Skip to main content
POST
Propose an edit (diff preview + confirmation token)

The propose → confirm flow

Every write to an agent’s config, name, or description goes through two calls: a propose that previews the exact change as a diff and mints a confirmation token, and a confirm that sends the token back and applies exactly what was previewed — nothing else. This section walks through one complete round trip for an edit; proposeAssistantCreate and confirmAssistantCreate follow the same shape for creating a new agent. Draft-first, always. Both pairs only ever write to a draft agent. A published agent answers proposeAssistantEdits with 409 DRAFT_REQUIRED — you cannot edit production directly. If the published agent already has a paired draft, the error names it (metadata.draftAssistantId); otherwise, create one by calling proposeAssistantCreate/confirmAssistantCreate with metadata.productionAssistantId set to the published agent’s id (same deployment, same tenant). That anchors the new draft to it, which is how you stage a change to a live agent. Publishing the draft to production is a human action in the ClaudIA app — no public endpoint does it.

1. Propose

Send the change: one or more anchored edits (each replacing a verbatim excerpt of existing text), whole-value config/name/description keys, or both.
Request
The response previews the write and never applies it:
Response

2. Review the diff

diff is a unified diff (--- current / +++ proposed) computed over the whole assistant, not just the field(s) you touched: both sides are rendered as sorted key: value lines (two spaces per nesting level, long prompts as block scalars) and diffed, so neighboring fields show up as context lines around your change — as in the example above, where model_name/system_prompt/tenant and tools/deployment_role/updated_at frame the one line that actually changed. Read it line by line, paying special attention to - lines — those are what disappears. Nothing has been written yet: if the diff looks wrong, discard it and send a corrected proposeAssistantEdits call instead of confirming.

3. Confirm

Send back only confirmationId, plus baseUpdatedAt as the If-Match header. No other body field is read — the server replays the exact proposal it stored server-side.
Request

4. The stubbed echo

The 200 response is the persisted agent, in the same shape getAssistant returns — including the same stub on long prompt fields. You already authored the new text in step 1, so it is not echoed back in full; read it again with readAssistantText if you need it.
Response
If confirmationId no longer resolves — the proposal’s TTL expired — the 404 names PROPOSAL_NOT_FOUND and coaches re-running proposeAssistantEdits with the same body. Unlike the create pair, an edits confirm is not consumed on success: retrying the exact same confirm after it already applied does not 404. Its own write moved updated_at, so the retry’s If-Match is now stale against the current agent and it fails the same way any other stale confirm does — 412 STALE_PRECONDITION. If you see that, re-read the agent with getAssistant first: the change may already be applied, in which case there is nothing left to do; only propose again if it genuinely is not there.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

tenant
string
required

Tenant whose agents you are managing. Discover the tenants your credentials cover with listMyClaudiaProjects. A tenant your credentials do not cover is indistinguishable from one that does not exist.

id
string
required

Assistant to operate on, as returned by listAssistants (assistant_id field).

Query Parameters

role
enum<string>
required

Deployment the assistant lives in: supervisor (orchestrator agents) or react (specialist agents), plus qna for knowledge-base Q&A agents. Read them with that role; they are CREATED through proposeAssistantCreate as deployment: react with graphId: qna_agent, and the platform derives the qna role from the graph. listAssistants returns it as deployment_role on each row — pass that value back here verbatim. A qna agent follows the same draft rule as any other: only a draft accepts writes, and a published one answers 409 naming its draft.

Available options:
supervisor,
react,
qna

Body

application/json

The change to apply: anchored edits, whole-value keys, or both.

Anchored text edits and/or whole-value patch keys; at least one of edits, config, name or description must carry a change.

name
string

New display name. Omit to keep it; it cannot be null or blank.

description
string | null

This assistant's routing description. Omit to keep it; a JSON null clears it.

config
object

Whole-value config edit: the agent's config keys DIRECTLY (flat, no configurable wrapper) for everything you are NOT editing with anchors (mcp_servers, agents, reasoning_effort, …). A field targeted by edits must NOT also appear here. Send it as a JSON OBJECT — never as a JSON-encoded string.

edits
object[]

The anchored replacements to apply, in order — each one sees the previous one's result. Every entry must target a text field (config.system_prompt, config.tone_of_voice_prompt, description) and match an excerpt that occurs exactly once. Omit it when the change is whole-value only.

Response

The confirmation contract: message (review + confirm instructions), diff (git unified format), confirmationId and baseUpdatedAt — send the latter back as If-Match on confirmAssistantEdits.

The response is of type object.