{"openapi":"3.1.0","info":{"title":"Charla API","version":"1.0.0","description":"Public developer API of Charla. Docs as Markdown at `/docs/<page>.md`, index at `/llms.txt`, agent setup at `/setup.md`. Errors: `{ error: { code, message, details } }`."},"servers":[{"url":"https://usecharla.com","description":"Production"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Agents","description":"Agents, versions and notices (`docs/10` §2.1)"},{"name":"Config","description":"Keiki-compatible single-agent config"},{"name":"Audit","description":"Append-only audit log and its export (`docs/10` §2.6)"},{"name":"Keys","description":"Org API keys (`docs/10` §2.6)"},{"name":"People","description":"DSAR: export and erase a contact (`docs/10` §2.5)"},{"name":"Deployments","description":"Partner deployments, one client org each (`docs/10` §2.4, ADR-0023)"},{"name":"OpenAI","description":"Agents as models: OpenAI Chat Completions with the agent's slug as `model` (`docs/10` §3)"}],"paths":{"/api/v1/developer/agents":{"get":{"operationId":"listAgents","tags":["Agents"],"summary":"List the agents the key can act on","description":"An agent-bound key sees only its agent.\n\nScopes: `agents:read`.","x-required-scopes":["agents:read"],"parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The agents, without their config","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentSummary"}}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createAgent","tags":["Agents"],"summary":"Create an agent with its first version, active","description":"Scopes: `agents:write`.","x-required-scopes":["agents:write"],"parameters":[{"$ref":"#/components/parameters/OrgId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"harness":{"type":"string","enum":["cloud","external"]},"harness_config":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["push","inbox"]},"dispatchUrl":{"type":"string","format":"uri"},"timeoutMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"identity":{"type":"object","properties":{"webhookUrl":{"type":"string","format":"uri"},"secretRef":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"},"linking":{"type":"object","properties":{"linkUrl":{"type":"string","format":"uri"},"confirmUrl":{"type":"string","format":"uri"},"secret":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"}},"required":["linkUrl","confirmUrl","secret"]}},"required":["webhookUrl","secretRef"]},"actions":{"type":"object","properties":{"viewUrl":{"type":"string","maxLength":2048},"webhookUrl":{"type":"string","maxLength":2048,"format":"uri"},"secretRef":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"}}}}},{"type":"null"}]},"turn_deadline_ms":{"type":"integer","minimum":1000,"maximum":900000},"api_gateway_enabled":{"type":"boolean"},"model":{"type":"string","minLength":1},"reasoning_effort":{"type":"string","enum":["none","low","medium","high"]},"system_prompt":{"type":"string"},"max_steps":{"type":"integer","minimum":1,"maximum":50},"history_limit":{"type":"integer","minimum":1,"maximum":200},"locale":{"type":"string","enum":["es-MX","pt-BR","es-AR","es-CO","es-CL","es-PE","es-ES","pt-PT","it-IT","es-419","en-US","es-UY","es-EC","es-PY","es-BO","es-VE","es-CR","es-PA","es-GT","es-HN","es-SV","es-NI","es-DO","es-US"]},"disclosure":{"type":"object","properties":{"enabled":{"type":"boolean"},"text":{"type":"string"}},"required":["enabled"],"additionalProperties":false},"features":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"user_secrets":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Z0-9_]+$"},"label":{"type":"string","minLength":1},"description":{"type":"string"},"helpUrl":{"type":"string","format":"uri"},"prefix":{"type":"string"},"minLength":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["name","label"]}},"workflow":{"anyOf":[{"$ref":"#/components/schemas/Workflow"},{"type":"null"}],"description":"Replaces the stored workflow whole; `null` removes it"}},"required":["name","model","system_prompt"],"additionalProperties":false}}}},"responses":{"201":{"description":"The agent and its active config","headers":{"idempotent-replayed":{"description":"Present when this is the stored answer to an earlier request","schema":{"description":"Present when this is the stored answer to an earlier request","type":"string","const":"true"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"}},"required":["agent"],"additionalProperties":false}}}},"400":{"description":"`400 invalid_request` (`details.issues`) or `400 invalid_json`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"402":{"$ref":"#/components/responses/PlanRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"`409 conflict` (a concurrent change won; retry) or `409 idempotency_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`422 invalid_config` (`details.issues`), `422 eu_disclosure_required`, `422 disclosure_text_not_ai` or `422 idempotency_key_reused`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/developer/agents/{agentId}":{"get":{"operationId":"getAgent","tags":["Agents"],"summary":"Get an agent and its active config","description":"Archived agents included.\n\nScopes: `agents:read`.","x-required-scopes":["agents:read"],"parameters":[{"$ref":"#/components/parameters/AgentId"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The agent","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"}},"required":["agent"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 agent_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"operationId":"patchAgent","tags":["Agents"],"summary":"Update an agent","description":"Agent fields change in place; config fields append a new active version (none when the result equals the running config). `features` merges per feature.\n\nScopes: `agents:write`.","x-required-scopes":["agents:write"],"parameters":[{"$ref":"#/components/parameters/AgentId"},{"$ref":"#/components/parameters/OrgId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"harness":{"type":"string","enum":["cloud","external"]},"harness_config":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["push","inbox"]},"dispatchUrl":{"type":"string","format":"uri"},"timeoutMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"identity":{"type":"object","properties":{"webhookUrl":{"type":"string","format":"uri"},"secretRef":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"},"linking":{"type":"object","properties":{"linkUrl":{"type":"string","format":"uri"},"confirmUrl":{"type":"string","format":"uri"},"secret":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"}},"required":["linkUrl","confirmUrl","secret"]}},"required":["webhookUrl","secretRef"]},"actions":{"type":"object","properties":{"viewUrl":{"type":"string","maxLength":2048},"webhookUrl":{"type":"string","maxLength":2048,"format":"uri"},"secretRef":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"}}}}},{"type":"null"}]},"turn_deadline_ms":{"type":"integer","minimum":1000,"maximum":900000},"api_gateway_enabled":{"type":"boolean"},"model":{"type":"string","minLength":1},"reasoning_effort":{"type":"string","enum":["none","low","medium","high"]},"system_prompt":{"type":"string"},"max_steps":{"type":"integer","minimum":1,"maximum":50},"history_limit":{"type":"integer","minimum":1,"maximum":200},"locale":{"type":"string","enum":["es-MX","pt-BR","es-AR","es-CO","es-CL","es-PE","es-ES","pt-PT","it-IT","es-419","en-US","es-UY","es-EC","es-PY","es-BO","es-VE","es-CR","es-PA","es-GT","es-HN","es-SV","es-NI","es-DO","es-US"]},"disclosure":{"type":"object","properties":{"enabled":{"type":"boolean"},"text":{"type":"string"}},"required":["enabled"],"additionalProperties":false},"features":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"user_secrets":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Z0-9_]+$"},"label":{"type":"string","minLength":1},"description":{"type":"string"},"helpUrl":{"type":"string","format":"uri"},"prefix":{"type":"string"},"minLength":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["name","label"]}},"workflow":{"anyOf":[{"$ref":"#/components/schemas/Workflow"},{"type":"null"}],"description":"Replaces the stored workflow whole; `null` removes it"},"status":{"type":"string","enum":["active","paused"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated agent","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"}},"required":["agent"],"additionalProperties":false}}}},"400":{"description":"`400 invalid_request` (`details.issues`) or `400 invalid_json`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"402":{"$ref":"#/components/responses/PlanRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 agent_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`409 conflict` (a concurrent change won; retry) or `409 idempotency_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`422 invalid_config` (`details.issues`), `422 eu_disclosure_required`, `422 disclosure_text_not_ai` or `422 idempotency_key_reused`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"operationId":"archiveAgent","tags":["Agents"],"summary":"Archive an agent","description":"Idempotent. Lines and history stay.\n\nScopes: `agents:write`.","x-required-scopes":["agents:write"],"parameters":[{"$ref":"#/components/parameters/AgentId"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The archived agent","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/AgentSummary"}},"required":["agent"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 agent_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/developer/agents/{agentId}/versions":{"get":{"operationId":"listAgentVersions","tags":["Agents"],"summary":"List an agent's versions, newest first (up to 50)","description":"Scopes: `agents:read`.","x-required-scopes":["agents:read"],"parameters":[{"$ref":"#/components/parameters/AgentId"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentVersion"}}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 agent_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/developer/agents/{agentId}/versions/{versionId}/restore":{"post":{"operationId":"restoreAgentVersion","tags":["Agents"],"summary":"Restore a version","description":"Appends a version (`source: restore`) with that version's config and activates it. Restoring the running config changes nothing.\n\nScopes: `agents:write`.","x-required-scopes":["agents:write"],"parameters":[{"$ref":"#/components/parameters/AgentId"},{"in":"path","name":"versionId","schema":{"type":"string","description":"`agv_…`"},"required":true,"description":"`agv_…`"},{"$ref":"#/components/parameters/OrgId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"The agent, now on the restored config","headers":{"idempotent-replayed":{"description":"Present when this is the stored answer to an earlier request","schema":{"description":"Present when this is the stored answer to an earlier request","type":"string","const":"true"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"},"changed":{"type":"boolean","description":"`false` when the agent already ran that config"}},"required":["agent","changed"],"additionalProperties":false}}}},"400":{"description":"`400 invalid_request` (`details.issues`) or `400 invalid_json`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"402":{"$ref":"#/components/responses/PlanRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 agent_not_found` or `404 version_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`409 conflict` (a concurrent change won; retry) or `409 idempotency_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`422 invalid_config` (`details.issues`), `422 eu_disclosure_required`, `422 disclosure_text_not_ai` or `422 idempotency_key_reused`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/developer/agents/{agentId}/notice":{"post":{"operationId":"sendNotice","tags":["Agents"],"summary":"Tell the agent something; it decides whether to message the contact","description":"Scopes: `agents:write`.","x-required-scopes":["agents:write"],"parameters":[{"$ref":"#/components/parameters/AgentId"},{"$ref":"#/components/parameters/OrgId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4000,"description":"What the agent should know; it decides what to tell the contact"},"conversation":{"description":"Conversation id (`cnv_…`); required until broadcast lands","type":"string","minLength":1},"contact":{"description":"Reserved for contact targeting","type":"string","minLength":1}},"required":["text"]}}}},"responses":{"200":{"description":"What happened to the notice","headers":{"idempotent-replayed":{"description":"Present when this is the stored answer to an earlier request","schema":{"description":"Present when this is the stored answer to an earlier request","type":"string","const":"true"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"outcome":{"type":"string","enum":["ran","queued","unavailable"]},"conversations":{"type":"number","const":1},"ran":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"queued":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unavailable":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"results":{"type":"array","items":{"type":"object","properties":{"conversation":{"type":"string"},"outcome":{"type":"string","enum":["ran","queued","unavailable"]},"turnId":{"type":"string"}},"required":["conversation","outcome"],"additionalProperties":false}},"noticeId":{"type":"string"},"turnId":{"type":"string"},"reason":{"description":"Why nothing ran, when `outcome` is `unavailable`","type":"string","enum":["no_active_version","held","closed","opted_out","blocked","persisted","discarded","busy","shutting_down"]}},"required":["ok","outcome","conversations","ran","queued","unavailable","results","noticeId"],"additionalProperties":false}}}},"400":{"description":"`400 invalid_request`, `400 conversation_required` or `400 invalid_idempotency_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 agent_not_found` or `404 conversation_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`409 idempotency_in_progress` (a request with this `Idempotency-Key` is still running; `Retry-After: 1`), or a conflict this route documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`422 idempotency_key_reused`, or a refusal this route documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"`502 runtime_unavailable`: the agent runtime did not answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openai/chat/completions":{"post":{"operationId":"createChatCompletion","tags":["OpenAI"],"summary":"Run one turn of an agent as an OpenAI chat completion","description":"OpenAI's Chat Completions format: point any OpenAI SDK at `/api/v1/openai`. `model` is the agent's slug or id; the agent's API gateway must be on. `x-conversation-id` threads calls into one conversation with memory (without it each call is new; the answer's header names the one used). `temperature`, `max_tokens`, `seed` and other sampling parameters are ignored. `stream: true` answers `text/event-stream` (`chat.completion.chunk`, `: ping` every 15 s, `data: [DONE]`). Client `tools` end the answer with `finish_reason: tool_calls`; send the results as `tool` messages within 24 h under the same `x-conversation-id`. Non-streaming answers carry `charla: { conversation_id, agent_id, trace_id, pending_actions }` (`trace_id` is null, and there is no `x-charla-turn-id` header, when the agent's identity webhook answered with its `reply` and no turn ran); a streamed answer's last chunk carries `charla.pending_actions` when there are any. `pending_actions` are the tool calls this turn proposed that wait for the person's confirmation: decide them with `POST /api/v1/openai/actions/{actionId}/decide`.\n\nScopes: `agents:chat`.","x-required-scopes":["agents:chat"],"parameters":[{"$ref":"#/components/parameters/OrgId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"`chat.completion` (JSON), or `chat.completion.chunk` events when `stream: true`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletion"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"`400 validation_error`, `400 invalid_json`, `400 invalid_messages`, `400 invalid_tool_choice`, `400 unexpected_tool_result`, `400 duplicate_tool_result` or `400 invalid_conversation_id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"402":{"description":"`402 insufficient_credit`: the organization has no credit left","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 model_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`409 busy` (a turn of this conversation is running) or `409 agent_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"`500 turn_failed` or `500 turn_cancelled`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`502 runtime_unavailable`: the agent runtime did not answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openai/actions/{actionId}/decide":{"post":{"operationId":"decideAction","tags":["OpenAI"],"summary":"Approve or decline, for your user, an action a chat completion proposed","description":"A tool that needs the person's confirmation does not run in the turn: the chat completion lists it in `charla.pending_actions` (`id`, `card`, `expires_at`). Show the card in your app and send the person's answer here, with the same API key, `user` and `x-conversation-id` as the chat that proposed it. Only this request approves: the agent's text never does. The stored call runs before the answer (`status: completed | failed`). A second request changes nothing (`changed: false`); after `expires_at` the action only expires. The agent reads the outcome in the conversation's next turn.\n\nScopes: `agents:chat`.","x-required-scopes":["agents:chat"],"parameters":[{"$ref":"#/components/parameters/ActionId"},{"$ref":"#/components/parameters/OrgId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionDecisionRequest"}}}},"responses":{"200":{"description":"The action after the decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiActionDecision"}}}},"400":{"description":"`400 validation_error`, `400 invalid_json` or `400 invalid_conversation_id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"description":"`403 gateway_disabled` or `403 requires_speaker_scopes` (`details.missing`; still pending)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`404 action_not_found`: no such action for this key, `user` and conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`409 approval_requires_verified_surface`: the business's team approves it on the dashboard","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"`502 runtime_unavailable`: the agent runtime did not answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openai/models":{"get":{"operationId":"listModels","tags":["OpenAI"],"summary":"List the agents the key can call as models","description":"Agents with the API gateway on, by slug; an agent-bound key sees only its own.\n\nScopes: `agents:chat`.","x-required-scopes":["agents:chat"],"parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The models","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/developer/config":{"get":{"operationId":"getConfig","tags":["Config"],"summary":"Get an agent's active config","description":"The agent is `agent_id`, else an agent-bound key's own, else the org's only live agent.\n\nScopes: `config:read`.","x-required-scopes":["config:read"],"parameters":[{"in":"query","name":"agent_id","schema":{"description":"`agt_…`","type":"string"},"description":"`agt_…`"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The active config","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/Config"}},"required":["config"],"additionalProperties":false}}}},"400":{"description":"`400 agent_id_required`: the org has several live agents, or none","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 agent_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`409 no_active_version`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"operationId":"patchConfig","tags":["Config"],"summary":"Patch an agent's config","description":"Partial: only the fields sent change, and `features` merges per feature and field (`{ memory: { enabled: false } }` changes only that flag; `null` removes a feature). Appends a new active version unless nothing changed.\n\nScopes: `config:write`.","x-required-scopes":["config:write"],"parameters":[{"$ref":"#/components/parameters/OrgId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string"},"model":{"type":"string","minLength":1},"reasoning_effort":{"type":"string","enum":["none","low","medium","high"]},"system_prompt":{"type":"string"},"max_steps":{"type":"integer","minimum":1,"maximum":50},"history_limit":{"type":"integer","minimum":1,"maximum":200},"locale":{"type":"string","enum":["es-MX","pt-BR","es-AR","es-CO","es-CL","es-PE","es-ES","pt-PT","it-IT","es-419","en-US","es-UY","es-EC","es-PY","es-BO","es-VE","es-CR","es-PA","es-GT","es-HN","es-SV","es-NI","es-DO","es-US"]},"disclosure":{"type":"object","properties":{"enabled":{"type":"boolean"},"text":{"type":"string"}},"required":["enabled"],"additionalProperties":false},"features":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"user_secrets":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Z0-9_]+$"},"label":{"type":"string","minLength":1},"description":{"type":"string"},"helpUrl":{"type":"string","format":"uri"},"prefix":{"type":"string"},"minLength":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["name","label"]}},"workflow":{"anyOf":[{"$ref":"#/components/schemas/Workflow"},{"type":"null"}],"description":"Replaces the stored workflow whole; `null` removes it"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The resulting config","content":{"application/json":{"schema":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/Config"},"changed":{"type":"boolean","description":"`false` when the patch left the config as it was"}},"required":["config","changed"],"additionalProperties":false}}}},"400":{"description":"`400 invalid_request` (`details.issues`) or `400 invalid_json`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"402":{"$ref":"#/components/responses/PlanRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 agent_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`409 conflict` (a concurrent change won; retry) or `409 idempotency_in_progress`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`422 invalid_config` (`details.issues`), `422 eu_disclosure_required`, `422 disclosure_text_not_ai` or `422 idempotency_key_reused`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/developer/agents/{agentId}/account-links":{"delete":{"operationId":"revokeAgentAccountLinks","tags":["People"],"summary":"Revoke a tenant user's account links on an agent","description":"Every `linked` binding of `user_id` held by a contact of `channel` on this agent stops authorising: the contact's next message asks for the link again (ADR-0023 §3.6). `204` whether the user was linked or not, and on a repeat.\n\nScopes: `people:write`.","x-required-scopes":["people:write"],"parameters":[{"$ref":"#/components/parameters/AgentId"},{"in":"query","name":"channel","schema":{"type":"string","enum":["whatsapp","instagram","messenger","telegram","sms","email","voice","web","api","slack","teams"],"description":"The contact's channel"},"required":true,"description":"The contact's channel"},{"in":"query","name":"user_id","schema":{"type":"string","minLength":1,"maxLength":255,"description":"The tenant's `userId`, as its confirmation answered it"},"required":true,"description":"The tenant's `userId`, as its confirmation answered it"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"204":{"description":"Revoked, or nothing to revoke"},"400":{"description":"`400 invalid_request` (`details.issues`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 agent_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/deployments/{externalRef}/account-links":{"delete":{"operationId":"revokeDeploymentAccountLinks","tags":["Deployments"],"summary":"Revoke a tenant user's account links in a deployment","description":"With a partner key: every `linked` binding of `user_id` held by a contact of `channel` in the deployment's client org stops authorising (ADR-0023 §3.6). `204` whether the user was linked or not, and on a repeat; also while the deployment is being deleted.\n\nScopes: `deployments:write`.","x-required-scopes":["deployments:write"],"parameters":[{"$ref":"#/components/parameters/ExternalRef"},{"in":"query","name":"channel","schema":{"type":"string","enum":["whatsapp","instagram","messenger","telegram","sms","email","voice","web","api","slack","teams"],"description":"The contact's channel"},"required":true,"description":"The contact's channel"},{"in":"query","name":"user_id","schema":{"type":"string","minLength":1,"maxLength":255,"description":"The tenant's `userId`, as its confirmation answered it"},"required":true,"description":"The tenant's `userId`, as its confirmation answered it"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"204":{"description":"Revoked, or nothing to revoke"},"400":{"description":"`400 invalid_request` (`details.issues`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 deployment_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`409 deployment_provisioning`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"`503 registry_unavailable` or `503 region_unavailable` (`Retry-After: 5`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/developer/people/{contactId}":{"delete":{"operationId":"erasePerson","tags":["People"],"summary":"Erase everything about a contact","description":"Opens an erasure request (or answers the open one) that the runtime runs in the background. An already erased contact answers its last erasure with `200`, so repeating it is harmless.\n\nScopes: `people:write`.","x-required-scopes":["people:write"],"parameters":[{"$ref":"#/components/parameters/ContactId"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The contact was already erased: its last erasure","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"`dsr_…`"},"type":{"type":"string","enum":["export","erase"]},"status":{"type":"string","enum":["pending","running","completed","failed"]},"contact_id":{"type":"string","description":"`ctc_…`"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"completed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["id","type","status","contact_id","created_at","completed_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"202":{"description":"The erasure request, queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"`dsr_…`"},"type":{"type":"string","enum":["export","erase"]},"status":{"type":"string","enum":["pending","running","completed","failed"]},"contact_id":{"type":"string","description":"`ctc_…`"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"completed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["id","type","status","contact_id","created_at","completed_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 contact_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/developer/people/{contactId}/export":{"get":{"operationId":"getPersonExport","tags":["People"],"summary":"Get the latest export of a contact and its download link","description":"Once `completed`, `download_url` is a presigned link to the package, valid until `expires_at` (24 h after it was built).\n\nScopes: `people:read`.","x-required-scopes":["people:read"],"parameters":[{"$ref":"#/components/parameters/ContactId"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The latest export request","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"`dsr_…`"},"type":{"type":"string","enum":["export","erase"]},"status":{"type":"string","enum":["pending","running","completed","failed"]},"contact_id":{"type":"string","description":"`ctc_…`"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"completed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"download_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Presigned link to the package once `completed`, until `expires_at`"},"expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["id","type","status","contact_id","created_at","completed_at","download_url","expires_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 contact_not_found` or `404 export_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"exportPerson","tags":["People"],"summary":"Build a contact's data package","description":"Opens an export request (or answers the open one) that the runtime runs in the background; poll `GET` for the link.\n\nScopes: `people:write`.","x-required-scopes":["people:write"],"parameters":[{"$ref":"#/components/parameters/ContactId"},{"$ref":"#/components/parameters/OrgId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"The export request, queued","headers":{"idempotent-replayed":{"description":"Present when this is the stored answer to an earlier request","schema":{"description":"Present when this is the stored answer to an earlier request","type":"string","const":"true"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"`dsr_…`"},"type":{"type":"string","enum":["export","erase"]},"status":{"type":"string","enum":["pending","running","completed","failed"]},"contact_id":{"type":"string","description":"`ctc_…`"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"completed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["id","type","status","contact_id","created_at","completed_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 contact_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`409 idempotency_in_progress` (a request with this `Idempotency-Key` is still running; `Retry-After: 1`), or a conflict this route documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`422 idempotency_key_reused`, or a refusal this route documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/audit":{"get":{"operationId":"listAudit","tags":["Audit"],"summary":"List the org's audit log, newest first","description":"Every change made from the dashboard, the API or the MCP server: actor, action, target and a redacted diff. Filters are inclusive; `to=2026-11-13` covers that whole UTC day. `format=csv` exports up to 10 000 entries as CSV on plans with `audit_export` (Max and up), else `402 plan_required`.\n\nScopes: `audit:read`.","x-required-scopes":["audit:read"],"parameters":[{"in":"query","name":"from","schema":{"type":"string"}},{"in":"query","name":"to","schema":{"type":"string"}},{"in":"query","name":"actor","schema":{"type":"string","pattern":"^(member|api_key|system|mcp)(:[A-Za-z0-9_]+)?$"}},{"in":"query","name":"action","schema":{"type":"string","pattern":"^[a-z_]+(\\.[a-z_]+)*\\.?$"}},{"in":"query","name":"cursor","schema":{"type":"string","pattern":"^aud_[0-9A-Z]{26}$"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500}},{"in":"query","name":"format","schema":{"type":"string","enum":["json","csv"]}},{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"A page of entries (or the CSV file with `format=csv`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntry"}},"nextCursor":{"description":"Pass as `cursor` for older entries","type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/InvalidKey"},"402":{"description":"`402 plan_required`: `format=csv` needs `audit_export`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/keys":{"get":{"operationId":"listKeys","tags":["Keys"],"summary":"List the org's API keys, newest first","description":"Never their secrets.\n\nScopes: `keys:manage`.","x-required-scopes":["keys:manage"],"parameters":[{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The keys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createKey","tags":["Keys"],"summary":"Create an API key","description":"The secret is in this response only. A key cannot grant scopes it lacks.\n\nScopes: `keys:manage`.","x-required-scopes":["keys:manage"],"parameters":[{"$ref":"#/components/parameters/OrgId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"scopes":{"minItems":1,"type":"array","items":{"type":"string","enum":["config:read","config:write","agents:read","agents:write","tools:read","tools:write","lines:read","lines:write","secrets:read","secrets:write","alerts:read","alerts:write","usage:read","usage:write","people:read","people:write","outcomes:read","outcomes:write","handoffs:read","handoffs:write","deployments:read","deployments:write","trace_exporters:read","trace_exporters:write","webhooks:read","webhooks:write","agents:chat","keys:manage","audit:read","*"]}},"environment":{"default":"live","type":"string","enum":["live","test"]},"agentId":{"type":["string","null"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["name","scopes"]}}}},"responses":{"201":{"description":"The key and its secret","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ApiKey"},"secret":{"type":"string","description":"The whole token. Shown in this response only"}},"required":["key","secret"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`404 not_found`: `agentId` is not an agent of this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`422 invalid_request`: `expiresAt` is in the past","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/keys/{keyId}/rotate":{"post":{"operationId":"rotateKey","tags":["Keys"],"summary":"Rotate a key","description":"Same id, new secret; the old secret stops working at once.\n\nScopes: `keys:manage`.","x-required-scopes":["keys:manage"],"parameters":[{"in":"path","name":"keyId","schema":{"type":"string","description":"`key_…`"},"required":true,"description":"`key_…`"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The key and its new secret","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ApiKey"},"secret":{"type":"string","description":"The whole token. Shown in this response only"}},"required":["key","secret"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`409 key_revoked`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/keys/{keyId}/revoke":{"post":{"operationId":"revokeKey","tags":["Keys"],"summary":"Revoke a key","description":"Immediate and idempotent.\n\nScopes: `keys:manage`.","x-required-scopes":["keys:manage"],"parameters":[{"in":"path","name":"keyId","schema":{"type":"string","description":"`key_…`"},"required":true,"description":"`key_…`"},{"$ref":"#/components/parameters/OrgId"}],"responses":{"200":{"description":"The revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ApiKey"}},"required":["key"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"Workflow":{"type":"object","properties":{"nodes":{"minItems":1,"maxItems":50,"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"start"}},"required":["id","name","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"stage"},"instructions":{"type":"string","minLength":1,"maxLength":8000},"promptMode":{"default":"append","type":"string","enum":["append","replace"]},"inheritTools":{"default":true,"type":"boolean"},"tools":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"}}},"required":["id","name","type","instructions"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"end"}},"required":["id","name","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"say"},"text":{"type":"string","minLength":1,"maxLength":2000}},"required":["id","name","type","text"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"set_state"},"set":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"additionalProperties":{"type":"string","minLength":1,"maxLength":500}}},"required":["id","name","type","set"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"tool"},"tool":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"args":{"default":{},"type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]{0,63}$"},"additionalProperties":{"type":"string","minLength":1,"maxLength":500}}},"required":["id","name","type","tool"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"handoff"},"reason":{"type":"string","minLength":1,"maxLength":200},"summary":{"type":"string","minLength":1,"maxLength":2000}},"required":["id","name","type","reason"],"additionalProperties":false}],"type":"object"}},"transitions":{"maxItems":200,"type":"array","items":{"oneOf":[{"type":"object","properties":{"from":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"to":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"order":{"type":"integer","minimum":0,"maximum":999},"label":{"type":"string","minLength":1,"maxLength":40},"type":{"type":"string","const":"none"}},"required":["from","to","order","type"],"additionalProperties":false},{"type":"object","properties":{"from":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"to":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"order":{"type":"integer","minimum":0,"maximum":999},"label":{"type":"string","minLength":1,"maxLength":40},"type":{"type":"string","const":"llm"},"condition":{"type":"string","minLength":1,"maxLength":500}},"required":["from","to","order","type","condition"],"additionalProperties":false},{"type":"object","properties":{"from":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"to":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"order":{"type":"integer","minimum":0,"maximum":999},"label":{"type":"string","minLength":1,"maxLength":40},"type":{"type":"string","const":"expression"},"expression":{"type":"string","minLength":1,"maxLength":500}},"required":["from","to","order","type","expression"],"additionalProperties":false}],"type":"object"}},"settings":{"default":{"maxTransitionsPerTurn":3,"resetAfterHours":24},"type":"object","properties":{"maxTransitionsPerTurn":{"default":3,"type":"integer","minimum":1,"maximum":10},"resetAfterHours":{"default":24,"anyOf":[{"type":"integer","minimum":1,"maximum":2160},{"type":"null"}]}},"additionalProperties":false}},"required":["nodes","transitions"],"additionalProperties":false,"description":"The graph of stages an agent follows: `start`, `stage` and `end` nodes joined by directed transitions (`none`, `llm`, `expression`). Keys are camelCase. A stage names its tools by tool name. The graph is validated on every write (`422 invalid_config`)"},"ChatCompletionRequest":{"type":"object","properties":{"model":{"type":"string","minLength":1,"description":"The agent's slug or id (`agt_…`)"},"messages":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"role":{"type":"string","const":"system"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]}}]}},"required":["role","content"]},{"type":"object","properties":{"role":{"type":"string","const":"developer"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]}}]}},"required":["role","content"]},{"type":"object","properties":{"role":{"type":"string","const":"user"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]}}]},"name":{"type":"string"}},"required":["role","content"]},{"type":"object","properties":{"role":{"type":"string","const":"assistant"},"content":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]}}]},{"type":"null"}]},"tool_calls":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"type":{"default":"function","type":"string","const":"function"},"function":{"type":"object","properties":{"name":{"type":"string","minLength":1},"arguments":{"type":"string"}},"required":["name","arguments"]}},"required":["id","function"]}}},"required":["role"]},{"type":"object","properties":{"role":{"type":"string","const":"tool"},"tool_call_id":{"type":"string","minLength":1},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]}}]}},"required":["role","tool_call_id","content"]}],"type":"object"}},"stream":{"type":["boolean","null"]},"stream_options":{"anyOf":[{"type":"object","properties":{"include_usage":{"type":"boolean"}}},{"type":"null"}]},"tools":{"maxItems":64,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"function"},"function":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":{"type":"string"},"parameters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["name"]}},"required":["type","function"]}},"tool_choice":{"anyOf":[{"type":"string","enum":["none","auto","required"]},{"type":"object","properties":{"type":{"type":"string","const":"function"},"function":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"]}},"required":["type","function"]}]},"response_format":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"json_object"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"json_schema"},"json_schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string"},"schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"strict":{"type":["boolean","null"]}},"required":["name"]}},"required":["type","json_schema"]}],"type":"object"},"user":{"type":"string","minLength":1,"maxLength":128}},"required":["model","messages"]},"ActionDecisionRequest":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","decline"],"description":"The person's answer, given in your app (never inferred from the chat)"},"user":{"description":"The `user` the chat completion that proposed the action was sent with","type":"string","minLength":1,"maxLength":128},"reason":{"description":"Why it was declined, in the person's words","type":"string","maxLength":500}},"required":["decision"]},"AgentSummary":{"type":"object","properties":{"id":{"type":"string","description":"`agt_…`"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"harness":{"type":"string","enum":["cloud","external"]},"harness_config":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["push","inbox"]},"dispatchUrl":{"type":"string","format":"uri"},"timeoutMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"identity":{"type":"object","properties":{"webhookUrl":{"type":"string","format":"uri"},"secretRef":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"},"linking":{"type":"object","properties":{"linkUrl":{"type":"string","format":"uri"},"confirmUrl":{"type":"string","format":"uri"},"secret":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"}},"required":["linkUrl","confirmUrl","secret"],"additionalProperties":false}},"required":["webhookUrl","secretRef"],"additionalProperties":false},"actions":{"type":"object","properties":{"viewUrl":{"type":"string","maxLength":2048},"webhookUrl":{"type":"string","maxLength":2048,"format":"uri"},"secretRef":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"turn_deadline_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"api_gateway_enabled":{"type":"boolean","description":"Callable as a model on `/api/v1/openai` (T-123)"},"active_version_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","slug","status","harness","harness_config","turn_deadline_ms","api_gateway_enabled","active_version_id","created_at","updated_at"],"additionalProperties":false},"Agent":{"type":"object","properties":{"id":{"type":"string","description":"`agt_…`"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"harness":{"type":"string","enum":["cloud","external"]},"harness_config":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["push","inbox"]},"dispatchUrl":{"type":"string","format":"uri"},"timeoutMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"identity":{"type":"object","properties":{"webhookUrl":{"type":"string","format":"uri"},"secretRef":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"},"linking":{"type":"object","properties":{"linkUrl":{"type":"string","format":"uri"},"confirmUrl":{"type":"string","format":"uri"},"secret":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"}},"required":["linkUrl","confirmUrl","secret"],"additionalProperties":false}},"required":["webhookUrl","secretRef"],"additionalProperties":false},"actions":{"type":"object","properties":{"viewUrl":{"type":"string","maxLength":2048},"webhookUrl":{"type":"string","maxLength":2048,"format":"uri"},"secretRef":{"type":"string","pattern":"^[A-Z0-9_]{1,128}$"}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"turn_deadline_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"api_gateway_enabled":{"type":"boolean","description":"Callable as a model on `/api/v1/openai` (T-123)"},"active_version_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"version":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"config":{"anyOf":[{"$ref":"#/components/schemas/AgentConfig"},{"type":"null"}]}},"required":["id","name","slug","status","harness","harness_config","turn_deadline_ms","api_gateway_enabled","active_version_id","created_at","updated_at","version","config"],"additionalProperties":false},"AgentConfig":{"type":"object","properties":{"model":{"type":"string"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","low","medium","high"]},{"type":"null"}]},"system_prompt":{"type":"string"},"max_steps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"history_limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"locale":{"type":"string","enum":["es-MX","pt-BR","es-AR","es-CO","es-CL","es-PE","es-ES","pt-PT","it-IT","es-419","en-US","es-UY","es-EC","es-PY","es-BO","es-VE","es-CR","es-PA","es-GT","es-HN","es-SV","es-NI","es-DO","es-US"]},"disclosure":{"type":"object","properties":{"enabled":{"type":"boolean"},"text":{"type":["string","null"]}},"required":["enabled","text"],"additionalProperties":false},"features":{"type":"object","properties":{"memory":{"type":"object","properties":{"enabled":{"type":"boolean"},"workingMemory":{"type":"boolean"},"semanticRecall":{"type":"boolean"},"observational":{"type":"boolean"},"categories":{"type":"array","items":{"type":"string","minLength":1}}},"required":["enabled"],"additionalProperties":false},"steering":{"type":"object","properties":{"debounceWindowMs":{"type":"integer","minimum":0,"maximum":9007199254740991},"midTurnStrategy":{"type":"string","enum":["interrupt","append","queue"]},"maxBatch":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["debounceWindowMs","midTurnStrategy","maxBatch"],"additionalProperties":false},"media":{"type":"object","properties":{"audio":{"type":"string","enum":["transcribe","ignore"]},"image":{"type":"string","enum":["describe","ignore"]},"video":{"type":"string","enum":["describe","ignore"]},"document":{"type":"string","enum":["extract","ignore"]},"fallback":{"type":"string"}},"required":["audio","image","video","document","fallback"],"additionalProperties":false},"escalation":{"type":"object","properties":{"enabled":{"type":"boolean"},"requireConfirmation":{"type":"boolean"},"routes":{"type":"object","properties":{"webhook":{"type":"string","format":"uri"},"slack":{"type":"object","properties":{"channel":{"type":"string","minLength":1}},"required":["channel"],"additionalProperties":false},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"whatsapp":{"type":"object","properties":{"number":{"type":"string","minLength":1}},"required":["number"],"additionalProperties":false}},"additionalProperties":false}},"required":["enabled","requireConfirmation","routes"],"additionalProperties":false},"sandbox":{"type":"object","properties":{"enabled":{"type":"boolean"},"persistent":{"type":"boolean"},"maxExecTimeMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["enabled","persistent","maxExecTimeMs"],"additionalProperties":false},"browser":{"type":"object","properties":{"enabled":{"type":"boolean"},"handoff":{"type":"boolean"},"screenshotDelivery":{"type":"boolean"}},"required":["enabled","handoff","screenshotDelivery"],"additionalProperties":false},"promptCache":{"type":"boolean"},"blackboard":{"type":"boolean"},"payments":{"type":"object","properties":{"enabled":{"type":"boolean"},"provider":{"type":"string","enum":["mercadopago","stripe"]},"disabledReason":{"type":"string","const":"needs_setup"}},"required":["enabled","provider"],"additionalProperties":false},"appointments":{"type":"object","properties":{"enabled":{"type":"boolean"},"connectionId":{"type":"string","minLength":1},"timeZone":{"type":"string"},"resources":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"calendarId":{"type":"string","minLength":1,"maxLength":1024},"name":{"type":"string","minLength":1,"maxLength":80},"seats":{"type":"integer","minimum":1,"maximum":2000},"maxPartySize":{"type":"integer","minimum":1,"maximum":2000}},"required":["calendarId","name"],"additionalProperties":false}},"services":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"aliases":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"durationMinutes":{"type":"integer","minimum":5,"maximum":480},"bufferMinutes":{"type":"integer","minimum":0,"maximum":240},"resources":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"required":["name","durationMinutes"],"additionalProperties":false}},"openingHours":{"type":"object","properties":{"mon":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"tue":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"wed":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"thu":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"fri":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"sat":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"sun":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}}},"additionalProperties":false},"minNoticeMinutes":{"type":"integer","minimum":0,"maximum":20160},"horizonDays":{"type":"integer","minimum":1,"maximum":365},"slotStepMinutes":{"type":"integer","minimum":5,"maximum":240}},"required":["enabled","connectionId","timeZone","resources","services","openingHours"],"additionalProperties":false},"followups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"dynamicUi":{"type":"boolean"},"guards":{"type":"object","properties":{"promptInjection":{"type":"boolean"},"pii":{"type":"string","enum":["redact","off"]},"moderation":{"type":"boolean"},"strictClaims":{"type":"boolean"}},"required":["promptInjection","pii","moderation"],"additionalProperties":false}},"additionalProperties":false,"description":"Stored feature flags (camelCase inside); `PATCH` merges them per feature"},"user_secrets":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Z0-9_]+$"},"label":{"type":"string","minLength":1},"description":{"type":"string"},"helpUrl":{"type":"string","format":"uri"},"prefix":{"type":"string"},"minLength":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["name","label"],"additionalProperties":false}},"workflow":{"anyOf":[{"$ref":"#/components/schemas/WorkflowOutput"},{"type":"null"}],"description":"`null` when the agent has no workflow"}},"required":["model","reasoning_effort","system_prompt","max_steps","history_limit","locale","disclosure","features","user_secrets","workflow"],"additionalProperties":false},"AgentVersion":{"type":"object","properties":{"id":{"type":"string","description":"`agv_…`"},"agent_id":{"type":"string"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source":{"type":"string","enum":["dashboard","sync","api","restore"]},"active":{"type":"boolean"},"config_hash":{"type":"string"},"config":{"anyOf":[{"$ref":"#/components/schemas/AgentConfig"},{"type":"null"}],"description":"`null` when an old version no longer parses under today's schema"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","agent_id","version","source","active","config_hash","config","created_at"],"additionalProperties":false},"ChatCompletion":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"ApiActionDecision":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/ApiAction"},"changed":{"type":"boolean","description":"`false`: it was already decided or expired before; nothing ran this time"}},"required":["action","changed"],"additionalProperties":false},"ApiAction":{"type":"object","properties":{"id":{"type":"string","description":"`act_…`: the id to decide"},"group_id":{"type":"string","description":"`grp_…`: the actions one turn proposed"},"tool":{"type":"string","description":"The tool that runs on approval"},"description":{"description":"The agent's walkthrough, if any","type":["string","null"]},"card":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"The approval card (`ApprovalCard`), built from the stored call"},"status":{"type":"string","enum":["pending","executing","completed","failed","declined","superseded","expired"]},"decided_via":{"anyOf":[{"type":"string","enum":["whatsapp_button","whatsapp_flow","chat_words","dashboard","slack","api","api_button"]},{"type":"null"}]},"result":{"description":"The tool's answer once `completed`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"decided_at":{"type":["string","null"]},"expires_at":{"type":"string","description":"After this, a decision only expires it"}},"required":["id","group_id","tool","description","card","status","decided_via","result","error","created_at","decided_at","expires_at"],"additionalProperties":false},"ModelList":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The agent's slug, for `model`"},"object":{"type":"string","const":"model"},"created":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"owned_by":{"type":"string"},"charla":{"type":"object","properties":{"agent_id":{"type":"string"},"name":{"type":"string"}},"required":["agent_id","name"],"additionalProperties":false}},"required":["id","object","created","owned_by","charla"],"additionalProperties":false}}},"required":["object","data"],"additionalProperties":false},"Config":{"type":"object","properties":{"agent_id":{"type":"string"},"version_id":{"type":"string"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"model":{"type":"string"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","low","medium","high"]},{"type":"null"}]},"system_prompt":{"type":"string"},"max_steps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"history_limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"locale":{"type":"string","enum":["es-MX","pt-BR","es-AR","es-CO","es-CL","es-PE","es-ES","pt-PT","it-IT","es-419","en-US","es-UY","es-EC","es-PY","es-BO","es-VE","es-CR","es-PA","es-GT","es-HN","es-SV","es-NI","es-DO","es-US"]},"disclosure":{"type":"object","properties":{"enabled":{"type":"boolean"},"text":{"type":["string","null"]}},"required":["enabled","text"],"additionalProperties":false},"features":{"type":"object","properties":{"memory":{"type":"object","properties":{"enabled":{"type":"boolean"},"workingMemory":{"type":"boolean"},"semanticRecall":{"type":"boolean"},"observational":{"type":"boolean"},"categories":{"type":"array","items":{"type":"string","minLength":1}}},"required":["enabled"],"additionalProperties":false},"steering":{"type":"object","properties":{"debounceWindowMs":{"type":"integer","minimum":0,"maximum":9007199254740991},"midTurnStrategy":{"type":"string","enum":["interrupt","append","queue"]},"maxBatch":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["debounceWindowMs","midTurnStrategy","maxBatch"],"additionalProperties":false},"media":{"type":"object","properties":{"audio":{"type":"string","enum":["transcribe","ignore"]},"image":{"type":"string","enum":["describe","ignore"]},"video":{"type":"string","enum":["describe","ignore"]},"document":{"type":"string","enum":["extract","ignore"]},"fallback":{"type":"string"}},"required":["audio","image","video","document","fallback"],"additionalProperties":false},"escalation":{"type":"object","properties":{"enabled":{"type":"boolean"},"requireConfirmation":{"type":"boolean"},"routes":{"type":"object","properties":{"webhook":{"type":"string","format":"uri"},"slack":{"type":"object","properties":{"channel":{"type":"string","minLength":1}},"required":["channel"],"additionalProperties":false},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"whatsapp":{"type":"object","properties":{"number":{"type":"string","minLength":1}},"required":["number"],"additionalProperties":false}},"additionalProperties":false}},"required":["enabled","requireConfirmation","routes"],"additionalProperties":false},"sandbox":{"type":"object","properties":{"enabled":{"type":"boolean"},"persistent":{"type":"boolean"},"maxExecTimeMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["enabled","persistent","maxExecTimeMs"],"additionalProperties":false},"browser":{"type":"object","properties":{"enabled":{"type":"boolean"},"handoff":{"type":"boolean"},"screenshotDelivery":{"type":"boolean"}},"required":["enabled","handoff","screenshotDelivery"],"additionalProperties":false},"promptCache":{"type":"boolean"},"blackboard":{"type":"boolean"},"payments":{"type":"object","properties":{"enabled":{"type":"boolean"},"provider":{"type":"string","enum":["mercadopago","stripe"]},"disabledReason":{"type":"string","const":"needs_setup"}},"required":["enabled","provider"],"additionalProperties":false},"appointments":{"type":"object","properties":{"enabled":{"type":"boolean"},"connectionId":{"type":"string","minLength":1},"timeZone":{"type":"string"},"resources":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"calendarId":{"type":"string","minLength":1,"maxLength":1024},"name":{"type":"string","minLength":1,"maxLength":80},"seats":{"type":"integer","minimum":1,"maximum":2000},"maxPartySize":{"type":"integer","minimum":1,"maximum":2000}},"required":["calendarId","name"],"additionalProperties":false}},"services":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"aliases":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"durationMinutes":{"type":"integer","minimum":5,"maximum":480},"bufferMinutes":{"type":"integer","minimum":0,"maximum":240},"resources":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"required":["name","durationMinutes"],"additionalProperties":false}},"openingHours":{"type":"object","properties":{"mon":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"tue":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"wed":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"thu":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"fri":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"sat":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}},"sun":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false}}},"additionalProperties":false},"minNoticeMinutes":{"type":"integer","minimum":0,"maximum":20160},"horizonDays":{"type":"integer","minimum":1,"maximum":365},"slotStepMinutes":{"type":"integer","minimum":5,"maximum":240}},"required":["enabled","connectionId","timeZone","resources","services","openingHours"],"additionalProperties":false},"followups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"dynamicUi":{"type":"boolean"},"guards":{"type":"object","properties":{"promptInjection":{"type":"boolean"},"pii":{"type":"string","enum":["redact","off"]},"moderation":{"type":"boolean"},"strictClaims":{"type":"boolean"}},"required":["promptInjection","pii","moderation"],"additionalProperties":false}},"additionalProperties":false,"description":"Stored feature flags (camelCase inside); `PATCH` merges them per feature"},"user_secrets":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Z0-9_]+$"},"label":{"type":"string","minLength":1},"description":{"type":"string"},"helpUrl":{"type":"string","format":"uri"},"prefix":{"type":"string"},"minLength":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["name","label"],"additionalProperties":false}},"workflow":{"anyOf":[{"$ref":"#/components/schemas/WorkflowOutput"},{"type":"null"}],"description":"`null` when the agent has no workflow"}},"required":["agent_id","version_id","version","model","reasoning_effort","system_prompt","max_steps","history_limit","locale","disclosure","features","user_secrets","workflow"],"additionalProperties":false},"AuditEntry":{"type":"object","properties":{"id":{"type":"string","description":"`aud_…`, time-ordered"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["member","api_key","system","mcp"]},"id":{"description":"`mem_…`, `key_…`; null for the system","type":["string","null"]}},"required":["type","id"],"additionalProperties":false},"action":{"type":"string","description":"`<target>.<verb>`, e.g. `agent.version.create`"},"target":{"anyOf":[{"type":"object","properties":{"type":{"type":"string"},"id":{"type":["string","null"]}},"required":["type","id"],"additionalProperties":false},{"type":"null"}]},"diff":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Ids and changed fields, redacted: never a secret value"},"ip":{"type":["string","null"]}},"required":["id","createdAt","actor","action","target","diff","ip"],"additionalProperties":false},"ApiKey":{"type":"object","properties":{"id":{"type":"string","description":"`key_…`"},"name":{"type":"string"},"agentId":{"description":"Set on agent-bound keys","type":["string","null"]},"environment":{"type":"string","enum":["live","test"]},"hint":{"type":"string","description":"`sk_live_…abcd`: recognises a key without revealing it"},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"createdBy":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"rotatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","name","agentId","environment","hint","scopes","expiresAt","revokedAt","lastUsedAt","createdBy","createdAt","rotatedAt"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable snake_case code; branch on it, not on message"},"message":{"type":"string","description":"Human-readable, may change"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Code-specific; {} if none"}},"required":["code","message","details"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"title":"Error"},"WorkflowOutput":{"type":"object","properties":{"nodes":{"minItems":1,"maxItems":50,"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"start"}},"required":["id","name","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"stage"},"instructions":{"type":"string","minLength":1,"maxLength":8000},"promptMode":{"default":"append","type":"string","enum":["append","replace"]},"inheritTools":{"default":true,"type":"boolean"},"tools":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"}}},"required":["id","name","type","instructions","promptMode","inheritTools","tools"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"end"}},"required":["id","name","type"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"say"},"text":{"type":"string","minLength":1,"maxLength":2000}},"required":["id","name","type","text"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"set_state"},"set":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"additionalProperties":{"type":"string","minLength":1,"maxLength":500}}},"required":["id","name","type","set"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"tool"},"tool":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"args":{"default":{},"type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]{0,63}$"},"additionalProperties":{"type":"string","minLength":1,"maxLength":500}}},"required":["id","name","type","tool","args"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"name":{"type":"string","minLength":1,"maxLength":60},"position":{"type":"object","properties":{"x":{"type":"number","minimum":-100000,"maximum":100000},"y":{"type":"number","minimum":-100000,"maximum":100000}},"required":["x","y"],"additionalProperties":false},"type":{"type":"string","const":"handoff"},"reason":{"type":"string","minLength":1,"maxLength":200},"summary":{"type":"string","minLength":1,"maxLength":2000}},"required":["id","name","type","reason"],"additionalProperties":false}],"type":"object"}},"transitions":{"maxItems":200,"type":"array","items":{"oneOf":[{"type":"object","properties":{"from":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"to":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"order":{"type":"integer","minimum":0,"maximum":999},"label":{"type":"string","minLength":1,"maxLength":40},"type":{"type":"string","const":"none"}},"required":["from","to","order","type"],"additionalProperties":false},{"type":"object","properties":{"from":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"to":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"order":{"type":"integer","minimum":0,"maximum":999},"label":{"type":"string","minLength":1,"maxLength":40},"type":{"type":"string","const":"llm"},"condition":{"type":"string","minLength":1,"maxLength":500}},"required":["from","to","order","type","condition"],"additionalProperties":false},{"type":"object","properties":{"from":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"to":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"order":{"type":"integer","minimum":0,"maximum":999},"label":{"type":"string","minLength":1,"maxLength":40},"type":{"type":"string","const":"expression"},"expression":{"type":"string","minLength":1,"maxLength":500}},"required":["from","to","order","type","expression"],"additionalProperties":false}],"type":"object"}},"settings":{"default":{"maxTransitionsPerTurn":3,"resetAfterHours":24},"type":"object","properties":{"maxTransitionsPerTurn":{"default":3,"type":"integer","minimum":1,"maximum":10},"resetAfterHours":{"default":24,"anyOf":[{"type":"integer","minimum":1,"maximum":2160},{"type":"null"}]}},"required":["maxTransitionsPerTurn","resetAfterHours"],"additionalProperties":false}},"required":["nodes","transitions","settings"],"additionalProperties":false,"description":"The graph of stages an agent follows: `start`, `stage` and `end` nodes joined by directed transitions (`none`, `llm`, `expression`). Keys are camelCase. A stage names its tools by tool name. The graph is validated on every write (`422 invalid_config`)"}},"headers":{"X-RateLimit-Limit":{"required":true,"description":"Requests the key may make in any 60 s window","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Requests the key may make in any 60 s window"}},"X-RateLimit-Remaining":{"required":true,"description":"Requests left in the current window","schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Requests left in the current window"}}},"responses":{"ValidationError":{"description":"`400 validation_error` (`details.issues`: the Zod issues) or `400 invalid_json`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidKey":{"description":"`401 invalid_key`: missing, malformed, unknown, expired or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PlanRequired":{"description":"`402 plan_required`: the org's plan does not allow it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"`403 insufficient_scope` (`details`: `{ required, missing }`), `org_key_required` or `org_mismatch`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"`404 not_found`: missing, or not visible to this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"`409 conflict`: the resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"`429 rate_limited`: the key's per-minute limit is spent","headers":{"X-RateLimit-Limit":{"description":"Requests the key may make in any 60 s window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until a request fits","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"`500 internal_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"OrgId":{"in":"header","name":"x-org-id","schema":{"description":"The org a platform key acts on; an org key may send only its own","type":"string"},"description":"The org a platform key acts on; an org key may send only its own"},"IdempotencyKey":{"in":"header","name":"idempotency-key","schema":{"description":"Replays the first answer for 24 h (`Idempotent-Replayed: true`) instead of running again","type":"string","minLength":1,"maxLength":255},"description":"Replays the first answer for 24 h (`Idempotent-Replayed: true`) instead of running again"},"AgentId":{"in":"path","name":"agentId","schema":{"type":"string","description":"`agt_…`"},"required":true,"description":"`agt_…`"},"ActionId":{"in":"path","name":"actionId","schema":{"type":"string","description":"`act_…`"},"required":true,"description":"`act_…`"},"ExternalRef":{"in":"path","name":"externalRef","schema":{"type":"string","description":"The partner's id of the deployment"},"required":true,"description":"The partner's id of the deployment"},"ContactId":{"in":"path","name":"contactId","schema":{"type":"string","description":"`ctc_…`"},"required":true,"description":"`ctc_…`"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer sk_live_…` (or `sk_test_…`)"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}}}}