Edit draft configuration
Partial update. Settings merge one level; arrays replace their field. Does not change live calls. Unsupported voice or setting is refused, not silently substituted. retrieval_snapshot_id and fallback_source_ids remain accepted and eligibility-checked as tenant-safe compatibility data, but publication ignores them and freezes the direct agent library. An archived agent is refused with agent_archived.
Authentication
Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.
Path parameters
Headers
Strong ETag from the resource being changed. Draft/tool/variable/publication operations use the complete agent draft ETag; number operations use the number ETag; MCP update uses its own ETag. Never retry a stale edit by blindly using a fresh ETag. Agent identity edits use the identity ETag; knowledge-source reingest uses the source ETag. A stale revision returns 409: draft_conflict for agent, draft, variable, tool, MCP server and publication-token checks; conflict with details.reason=stale_revision for phone numbers and knowledge sources. A missing header returns 428 revision_required. Same-intent replay uses the original If-Match and returns its receipt before checking current revision.
Stable key per logical intent, 1–255 printable characters. Persist it before sending. Retry the same key/body after an uncertain result for 24 hours. A changed body conflicts. Beyond retention, reconcile the resource before retrying; this is not permanent deduplication. Current authorization is rechecked on replay. Evaluation order: authenticate and check current authorization; look up intent; replay its stored receipt before checking the current revision; only a new intent evaluates If-Match and executes. Fingerprint includes method, path, body and original If-Match. A changed request returns idempotency_key_reused. The server stores only a keyed (HMAC) fingerprint, and no error or response ever returns a fingerprint or hash of a request. In-flight intent returns 409 idempotency_in_progress with Retry-After; retry the same intent after reconciliation. Receipts describe that attempt, not current resource state. A replay returns the original status code and body, with the response header Idempotent-Replayed: true.
Request
Partial merge of these named settings. Absent fields keep their values. Null resets only nullable fields to platform defaults/unset. Arrays replace their field; extraction_fields=[] removes definitions. No serving-model, checkpoint, temperature or campaign retry knobs. Draft excludes inactive noise-suppression controls.
Retained compatibility field. Values must identify current fallback sources eligible for this agent: agent-owned sources or linked workspace sources. Publication ignores this field and freezes fallback context from the direct agent library. A write replaces the entire compatibility list.
Per-key merge: each policy you include merges field by field; policies you omit stay unchanged. New built-in policies may be added later; older clients that omit them keep them unchanged. end_call is enabled by default for every agent; only an explicit end_call.enabled=false turns it off. transfer starts disabled with a null destination.
Response headers
true when this response replays a stored Idempotency-Key result. The status and body equal the original.
Response
Opaque publication token; equals the ETag. The ETag is the publication token. It covers the draft revision, the revision of each bound tool, the revision of each referenced MCP server, each pinned secret version, the direct agent library membership and source state/revision, and the default-tool policy. A change to any of them, including an MCP server edit shared by several agents, changes the token.
Discovered prompt references, not a guarantee of required-input validation. Undeclared per-call variables remain accepted.
Effective built-in policies. end_call is enabled by default for every agent, including agents created before this field existed; only an explicit end_call.enabled=false policy turns it off. transfer starts disabled with a null destination. Publication freezes the policy; rollback restores it subject to current revocation. Clients must accept additional policy keys.