{"openapi":"3.1.0","info":{"title":"Macha API","version":"1.0.0","summary":"Public REST API for the Macha AI copilot platform.","description":"Authoritative machine-readable contract for Macha's v1 REST API. Hand-maintained against backend/docs/api-v1-spec.md. Only endpoints that are actually shipped appear here; planned endpoints from the markdown spec are intentionally omitted until they go live.\n\nAuthentication: pass `Authorization: Bearer mka_live_<token>` on every request. Keys are scoped, each endpoint lists the required scope under `x-required-scope`.\n\nIdempotency: write endpoints honor an optional `Idempotency-Key` header (24h replay window). See the markdown spec section 5 for full semantics.","contact":{"name":"Macha Support","email":"hello@getmacha.com","url":"https://www.getmacha.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://dashboard.getmacha.com/api/v1","description":"Production"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Meta","description":"Discovery + spec endpoints."},{"name":"Agents","description":"AI agents, the core noun."},{"name":"Conversations","description":"Chat history. Read-only in v1.0."},{"name":"Connectors","description":"Connected third-party tools (Zendesk, Slack, etc.)."},{"name":"Custom tools","description":"User-defined HTTP endpoint tools."},{"name":"Sources","description":"Knowledge base sources."},{"name":"Chatbots","description":"Embeddable widget configurations."},{"name":"Triggers","description":"Webhook + scheduled automation."},{"name":"Team","description":"Org members."},{"name":"Analytics","description":"Per-agent usage stats."},{"name":"Organization","description":"Org-level info."}],"paths":{"/":{"get":{"tags":["Meta"],"summary":"Discovery banner.","operationId":"getApiInfo","description":"Returns a tiny banner with the API name, version, and docs URL. Useful as a smoke test. No authentication required.","security":[],"responses":{"200":{"description":"Banner.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["name","version","docs"],"properties":{"name":{"type":"string","example":"Macha API"},"version":{"type":"string","example":"v1"},"docs":{"type":"string","example":"https://www.getmacha.com/docs/api"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}}},"/openapi.json":{"get":{"tags":["Meta"],"summary":"Machine-readable OpenAPI 3.1 spec.","operationId":"getOpenApiSpec","description":"Returns this very document. Used by SDK generators and tooling.","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/agents":{"get":{"tags":["Agents"],"summary":"List agents.","operationId":"listAgents","x-required-scope":"agents:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"$ref":"#/components/responses/AgentList"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Agents"],"summary":"Create agent.","operationId":"createAgent","x-required-scope":"agents:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreate"}}}},"responses":{"201":{"$ref":"#/components/responses/Agent"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/agents/{id}":{"parameters":[{"$ref":"#/components/parameters/AgentId"}],"get":{"tags":["Agents"],"summary":"Fetch agent.","operationId":"getAgent","x-required-scope":"agents:read","responses":{"200":{"$ref":"#/components/responses/Agent"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["Agents"],"summary":"Update agent.","operationId":"updateAgent","x-required-scope":"agents:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUpdate"}}}},"responses":{"200":{"$ref":"#/components/responses/Agent"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Agents"],"summary":"Soft-delete agent.","operationId":"deleteAgent","description":"Soft delete. Restorable from the dashboard trash UI for 30 days; cleanup scheduler hard-deletes thereafter. Side effects: triggers deactivated and external webhooks torn down, chatbots paused.","x-required-scope":"agents:delete","responses":{"200":{"$ref":"#/components/responses/DeleteAck"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations.","operationId":"listConversations","description":"Returns the org's conversations newest-first. By default every conversation is visible (dashboard, autonomous, embed, sub-agent, simulation, onboarding), narrow with `source`, `is_simulation`, `is_onboarding`, or any of the metadata filters. Pagination via `cursor` + `limit`.","x-required-scope":"conversations:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"agent_id","in":"query","schema":{"type":"string"},"description":"Filter to one agent. Accepts `agent_<24 hex>` or a bare ObjectId."},{"name":"source","in":"query","schema":{"type":"string","enum":["dashboard","autonomous","embed","sub-agent"]},"description":"Filter to one source. Sub-agent runs are only visible when `source=sub-agent` is explicitly passed."},{"name":"model","in":"query","schema":{"type":"string"},"description":"Exact match against the model used (e.g. `gpt-5-mini`)."},{"name":"parent_conversation_id","in":"query","schema":{"type":"string"},"description":"Filter to sub-agent runs of one parent conversation. Accepts `conv_<24 hex>` or a bare ObjectId."},{"name":"conversation_number","in":"query","schema":{"type":"integer","minimum":1},"description":"Exact match against the per-org sequence number. Useful for 'fetch conversation #42'."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601. Filter `last_message_at >= since`. Back-compat alias for `last_message_after`."},{"name":"created_after","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601. Filter `created_at >= ...`."},{"name":"created_before","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601. Filter `created_at <= ...`."},{"name":"last_message_after","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601. Filter `last_message_at >= ...`."},{"name":"last_message_before","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601. Filter `last_message_at <= ...`."},{"name":"ticket_id","in":"query","schema":{"type":"string"},"description":"Shorthand: matches `metadata.ticketId`, `metadata.ticket_id`, OR `triggerPayload.ticket.id`. Both string and numeric forms are checked, so `?ticket_id=12345` matches whether the value was saved as an integer or a string."},{"name":"metadata","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":{"type":"string"}},"description":"Match against arbitrary keys on the Mixed `metadata` field. Pass as bracket notation, e.g. `?metadata[ticketId]=12345&metadata[priority]=high`. Keys starting with `$` or containing dots are rejected to prevent operator injection."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Case-insensitive regex search against `title` only. Tier A scope, does not search inside message content. Special regex characters are escaped."}],"responses":{"200":{"$ref":"#/components/responses/ConversationList"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/conversations/{id}":{"parameters":[{"$ref":"#/components/parameters/ConversationId"}],"get":{"tags":["Conversations"],"summary":"Fetch conversation with full message thread.","operationId":"getConversation","x-required-scope":"conversations:read","parameters":[{"name":"include_trigger_payload","in":"query","schema":{"type":"string","enum":["true","1"]},"description":"When `true` or `1`, the raw webhook payload that fired the autonomous run is included as `trigger_payload`. Off by default because it can contain customer PII (requester email, ticket body, etc.)."}],"responses":{"200":{"$ref":"#/components/responses/ConversationDetail"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/conversations/{id}/messages":{"parameters":[{"$ref":"#/components/parameters/ConversationId"}],"get":{"tags":["Conversations"],"summary":"Paginated message list for long conversations.","operationId":"listConversationMessages","x-required-scope":"conversations:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Page of messages.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"meta":{"$ref":"#/components/schemas/MetaWithCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/connectors":{"get":{"tags":["Connectors"],"summary":"List connectors.","operationId":"listConnectors","x-required-scope":"connectors:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Page of connector summaries.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorSummary"}},"meta":{"$ref":"#/components/schemas/MetaWithCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/connectors/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Connector ID, e.g. `connector_<24 hex>`. Raw ObjectIds are also accepted."}],"get":{"tags":["Connectors"],"summary":"Fetch connector with its tool surface.","operationId":"getConnector","x-required-scope":"connectors:read","responses":{"200":{"description":"Connector detail.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/ConnectorDetail"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/custom_tools":{"get":{"tags":["Custom tools"],"summary":"List custom tools.","operationId":"listCustomTools","x-required-scope":"custom_tools:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Page of custom tools.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomTool"}},"meta":{"$ref":"#/components/schemas/MetaWithCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Custom tools"],"summary":"Create custom tool.","operationId":"createCustomTool","x-required-scope":"custom_tools:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomToolCreate"}}}},"responses":{"201":{"$ref":"#/components/responses/CustomTool"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/custom_tools/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Custom tool ID, `tool_<24 hex>`."}],"get":{"tags":["Custom tools"],"summary":"Fetch custom tool.","operationId":"getCustomTool","x-required-scope":"custom_tools:read","responses":{"200":{"$ref":"#/components/responses/CustomTool"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["Custom tools"],"summary":"Update custom tool.","operationId":"updateCustomTool","x-required-scope":"custom_tools:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomToolUpdate"}}}},"responses":{"200":{"$ref":"#/components/responses/CustomTool"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Custom tools"],"summary":"Hard-delete custom tool.","operationId":"deleteCustomTool","description":"Hard delete. Custom tools have no trash UI. The tool is also pulled from every `agent.tools` array in the org.","x-required-scope":"custom_tools:delete","responses":{"200":{"$ref":"#/components/responses/DeleteAck"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sources":{"get":{"tags":["Sources"],"summary":"List sources.","operationId":"listSources","x-required-scope":"sources:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Page of sources.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"meta":{"$ref":"#/components/schemas/MetaWithCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Sources"],"summary":"Create a knowledge source.","operationId":"createSource","description":"Creates a `website` or `webpage` source. `type=upload` returns 409 (the Uploads source is a singleton per org and is already created automatically). `type=connector` returns 422 because connector sources are auto-created when the integration is added, use the connectors flow instead.","x-required-scope":"sources:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceCreate"}}}},"responses":{"201":{"description":"Source created.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Source"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sources/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Source ID, `source_<24 hex>`."}],"get":{"tags":["Sources"],"summary":"Fetch source.","operationId":"getSource","x-required-scope":"sources:read","responses":{"200":{"description":"Source.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Source"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Sources"],"summary":"Hard-delete a source.","operationId":"deleteSource","description":"Hard delete. Removes every Document belonging to the source AND pulls the source reference from every agent's `data_sources[]`. No trash / undo, this is irreversible.","x-required-scope":"sources:delete","responses":{"200":{"$ref":"#/components/responses/DeleteAck"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/chatbots":{"get":{"tags":["Chatbots"],"summary":"List chatbots.","operationId":"listChatbots","x-required-scope":"chatbots:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Page of chatbots.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Chatbot"}},"meta":{"$ref":"#/components/schemas/MetaWithCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/chatbots/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Chatbot ID, `chatbot_<24 hex>`."}],"get":{"tags":["Chatbots"],"summary":"Fetch chatbot.","operationId":"getChatbot","x-required-scope":"chatbots:read","responses":{"200":{"description":"Chatbot.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Chatbot"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/triggers":{"get":{"tags":["Triggers"],"summary":"List triggers.","operationId":"listTriggers","x-required-scope":"triggers:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Page of triggers.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Trigger"}},"meta":{"$ref":"#/components/schemas/MetaWithCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/triggers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Trigger ID, `trigger_<24 hex>`."}],"get":{"tags":["Triggers"],"summary":"Fetch trigger.","operationId":"getTrigger","x-required-scope":"triggers:read","responses":{"200":{"description":"Trigger.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Trigger"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/team":{"get":{"tags":["Team"],"summary":"List org members.","operationId":"listMembers","x-required-scope":"team:read","responses":{"200":{"description":"Members.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Member"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/analytics/agents/{agent_id}":{"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"},"description":"Agent ID, `agent_<24 hex>`."}],"get":{"tags":["Analytics"],"summary":"Per-agent usage stats.","operationId":"getAgentAnalytics","x-required-scope":"analytics:read","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Analytics payload.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","description":"Free-form analytics object. Shape will be locked down once the analytics tab UI ships.","additionalProperties":true},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/org":{"get":{"tags":["Organization"],"summary":"Fetch the org for the current API key.","operationId":"getOrg","x-required-scope":"org:read","responses":{"200":{"description":"Org.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Org"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mka_live_<token>","description":"Pass `Authorization: Bearer mka_live_<token>`. Scopes are documented per-operation under `x-required-scope` because HTTP bearer doesn't formally model scopes the way OAuth flows do."}},"parameters":{"Cursor":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque pagination cursor. Pass the value from a previous response's `meta.next_cursor`. Omit for the first page."},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size. Server enforces a hard cap of 100."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":128},"description":"Client-supplied key. If the same key appears within 24h with an identical body, the cached response is returned. Different body with the same key → `409 idempotency_key_reused`."},"AgentId":{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^(agent_[a-f0-9]{24}|[a-f0-9]{24})$"},"description":"Agent ID. Either `agent_<24 hex>` or a bare ObjectId."},"ConversationId":{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^(conv_[a-f0-9]{24}|[a-f0-9]{24})$"},"description":"Conversation ID. Either `conv_<24 hex>` or a bare ObjectId."}},"responses":{"Unauthorized":{"description":"Bad, missing, revoked, or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Valid key, but the key lacks the required scope OR the org is in a state that forbids the action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"State conflict: handle taken, idempotency key reused with a different body, unique-constraint collision, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationFailed":{"description":"Input validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Per-key rate limit exceeded. Inspect `Retry-After` and `X-RateLimit-*` headers.","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the more-constraining window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Agent":{"description":"Single agent.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Agent"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"AgentList":{"description":"Paginated list of agents.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"meta":{"$ref":"#/components/schemas/MetaWithCursor"}}}}}},"ConversationList":{"description":"Paginated list of conversations (without messages).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversationSummary"}},"meta":{"$ref":"#/components/schemas/MetaWithCursor"}}}}}},"ConversationDetail":{"description":"Conversation with full message thread.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/ConversationDetail"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"CustomTool":{"description":"Single custom tool.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/CustomTool"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"DeleteAck":{"description":"Delete confirmation. Subsequent calls to the same DELETE will 404 (naturally idempotent).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","deleted"],"properties":{"id":{"type":"string","example":"agent_64f1c..."},"deleted":{"type":"boolean","const":true}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}},"schemas":{"Meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","nullable":true,"example":"req_a1b2c3d4e5f6g7h8"}},"additionalProperties":true},"MetaWithCursor":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true,"description":"Pass to the next request's `?cursor=`. `null` when there's no next page."}}},"Error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","description":"Stable identifier. Customers code against this, not `message`."},"message":{"type":"string","description":"Human-readable. May change between releases."},"request_id":{"type":"string","nullable":true}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/Error"}}},"Agent":{"type":"object","required":["id","handle","name","is_active","tools_count","sub_agents_count"],"properties":{"id":{"type":"string","example":"agent_64f1c0..."},"handle":{"type":"string","example":"ticketTriage"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"model":{"type":"string","nullable":true,"example":"gpt-5-mini"},"is_active":{"type":"boolean"},"color":{"type":"string","nullable":true,"example":"#6366f1"},"avatar":{"type":"string","nullable":true},"tools_count":{"type":"integer","minimum":0},"sub_agents_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"ToolRef":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Base tool name, e.g. `zendesk_get_ticket`. Never the multi-instance suffix."},"connector_id":{"type":"string","nullable":true,"description":"Connector instance ID. `null` for built-in / knowledge tools."}}},"DataSourceRef":{"type":"object","required":["source_id","scope"],"properties":{"source_id":{"type":"string"},"scope":{"type":"string","enum":["all","selected"]},"documents":{"type":"array","items":{"type":"string"},"description":"When `scope = selected`, the document IDs to include."}}},"AgentCreate":{"type":"object","required":["handle","name"],"properties":{"handle":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9]*$","description":"camelCase alphanumeric. Unique within the org (case-insensitive)."},"name":{"type":"string"},"instructions":{"type":"string","description":"Required unless `instructions_html` is provided."},"instructions_html":{"type":"string"},"description":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"color":{"type":"string","default":"#6366f1"},"avatar":{"type":"string","nullable":true},"include_system_prompt":{"type":"boolean","default":true},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolRef"}},"connectors":{"type":"array","items":{"type":"string"}},"sub_agents":{"type":"array","items":{"type":"string"}},"data_sources":{"type":"array","items":{"$ref":"#/components/schemas/DataSourceRef"}},"pending_trigger_hint":{"type":"object","nullable":true,"additionalProperties":true}}},"AgentUpdate":{"type":"object","description":"Any subset of `AgentCreate` fields, plus the activation controls below. Omitted fields are unchanged.","properties":{"handle":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9]*$"},"name":{"type":"string"},"instructions":{"type":"string"},"instructions_html":{"type":"string"},"description":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"color":{"type":"string"},"avatar":{"type":"string","nullable":true},"include_system_prompt":{"type":"boolean"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolRef"}},"connectors":{"type":"array","items":{"type":"string"}},"sub_agents":{"type":"array","items":{"type":"string"}},"data_sources":{"type":"array","items":{"$ref":"#/components/schemas/DataSourceRef"}},"is_active":{"type":"boolean","description":"Activation guard: rejected if any assigned connector is `auth_failed`."},"deactivated_reason":{"type":"string","nullable":true},"deactivated_at":{"type":"string","format":"date-time","nullable":true},"pending_trigger_hint":{"type":"object","nullable":true,"additionalProperties":true}}},"ConversationSummary":{"type":"object","required":["id","source","autonomous","is_onboarding","is_simulation","credits_used"],"properties":{"id":{"type":"string"},"title":{"type":"string","nullable":true,"description":"LLM-generated summary of what the conversation is about."},"source":{"type":"string","enum":["dashboard","autonomous","embed","sub-agent"]},"agent_id":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"autonomous":{"type":"boolean"},"is_onboarding":{"type":"boolean","description":"The one-time post-onboarding welcome conversation."},"is_simulation":{"type":"boolean","description":"Test-run conversation fired via the agent builder's 'Test run' button."},"conversation_number":{"type":"integer","nullable":true,"description":"Per-org sequential number. `null` for sub-agent runs (they don't get a number)."},"parent_conversation_id":{"type":"string","nullable":true,"description":"Set on sub-agent runs. Points at the parent conversation."},"credits_used":{"type":"integer","minimum":0,"description":"Credits deducted for this conversation across all assistant responses."},"metadata":{"type":"object","nullable":true,"additionalProperties":true,"description":"Free-form metadata attached at creation time. Common keys: `ticketId`, `ticket_id`, plus connector-specific extras. Filterable via `?metadata[KEY]=VALUE` on the list endpoint."},"message_count":{"type":"integer","nullable":true,"minimum":0,"description":"Number of messages in the conversation. Returns `null` in list responses (we don't load the messages array there); the detail endpoint returns the real count."},"last_message_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"ConversationDetail":{"allOf":[{"$ref":"#/components/schemas/ConversationSummary"},{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"trigger_payload":{"description":"Raw webhook payload that fired this autonomous run. Present ONLY when the caller passed `?include_trigger_payload=true`. Shape is provider-specific.","nullable":true}}}]},"Message":{"type":"object","required":["role","content"],"properties":{"id":{"type":"string","nullable":true},"role":{"type":"string","enum":["user","assistant","tool","system"]},"content":{"type":"string","description":"User/assistant messages are plain text. Tool messages may carry a JSON blob, consumers should attempt JSON.parse before treating it as text."},"tool_calls":{"type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"arguments":{"type":"string","description":"JSON-stringified arguments to the tool."},"status":{"type":"string","nullable":true}}}},"tool_call_id":{"type":"string","nullable":true},"tool_name":{"type":"string","nullable":true},"connector_type":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"ConnectorSummary":{"type":"object","required":["id","type","name","status","is_active"],"properties":{"id":{"type":"string"},"type":{"type":"string","example":"zendesk"},"name":{"type":"string","description":"Display name. Distinguishes multiple instances of the same `type`."},"status":{"type":"string","enum":["connected","auth_failed","token_expired"]},"status_reason":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"ConnectorDetail":{"allOf":[{"$ref":"#/components/schemas/ConnectorSummary"},{"type":"object","required":["tools"],"properties":{"tools":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["read","write"]},"requires_confirmation":{"type":"boolean"},"disabled":{"type":"boolean","description":"`true` if this tool has been turned off for this connector instance via the dashboard."}}}}}}]},"CustomTool":{"type":"object","required":["id","name","label","description","method","url","type","auth","headers","parameters"],"properties":{"id":{"type":"string"},"name":{"type":"string","description":"Auto-generated from label, prefixed `custom_`. Immutable after creation."},"label":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["read","write"]},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"url":{"type":"string","description":"May contain `{{param}}` placeholders that get substituted at execute time."},"headers":{"type":"object","additionalProperties":{"type":"string"}},"body_template":{"type":"string","nullable":true,"description":"JSON string template for POST/PUT/PATCH bodies. Supports `{{param}}`."},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/CustomToolParam"}},"auth":{"type":"object","description":"Auth type + header_name only. Credentials are NEVER returned.","required":["type"],"properties":{"type":{"type":"string","enum":["none","bearer","api_key","basic"]},"header_name":{"type":"string","nullable":true,"description":"Only set when `type = api_key`."}}},"group":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"icon":{"type":"string","nullable":true},"color":{"type":"string","nullable":true}}},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"CustomToolParam":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"type":{"type":"string","default":"string","description":"JSON schema primitive, string, number, boolean, integer."},"description":{"type":"string"},"required":{"type":"boolean","default":false},"in":{"type":"string","enum":["query","header","body"],"description":"Where the param is sent. Default `query` for GET, `body` otherwise."},"headerName":{"type":"string","description":"Used when `in = header`. The actual HTTP header name."}}},"CustomToolAuthInput":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["none","bearer","api_key","basic"]},"credentials":{"type":"object","description":"Raw secrets. Encrypted at rest, never returned in responses. Send a fresh `credentials` object to rotate.","properties":{"token":{"type":"string","description":"Used when `type = bearer`."},"apiKey":{"type":"string","description":"Used when `type = api_key`."},"header_name":{"type":"string","description":"Header to put the api_key into. Default `X-API-Key`."},"username":{"type":"string","description":"Used when `type = basic`."},"password":{"type":"string","description":"Used when `type = basic`."}}}}},"CustomToolCreate":{"type":"object","required":["label","description","method","url"],"properties":{"label":{"type":"string","description":"Human-readable name. Include connector + resource (e.g. 'List Postmark Templates', not 'List Templates')."},"description":{"type":"string","description":"LLM-facing description. Determines when the tool is called."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"url":{"type":"string"},"type":{"type":"string","enum":["read","write"],"default":"read"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"body_template":{"type":"string","nullable":true},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/CustomToolParam"}},"response_mapping":{"type":"string","nullable":true,"description":"Dot path into the response, e.g. `data.items`."},"auth":{"$ref":"#/components/schemas/CustomToolAuthInput"},"group":{"type":"object","properties":{"name":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"}}}}},"CustomToolUpdate":{"type":"object","description":"Any subset of `CustomToolCreate` fields plus `is_active`. The tool's `name` is immutable.","properties":{"label":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["read","write"]},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"url":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"body_template":{"type":"string","nullable":true},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/CustomToolParam"}},"response_mapping":{"type":"string","nullable":true},"auth":{"$ref":"#/components/schemas/CustomToolAuthInput"},"is_active":{"type":"boolean"},"group":{"type":"object","properties":{"name":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"}}}}},"Source":{"type":"object","required":["id","type","name","sync_status","is_active"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["upload","website","webpage","connector"],"description":"How the source was created. `connector` sources are auto-created when a Google / Notion / Confluence / Zendesk Help Center integration is added. `upload` is the org-wide singleton for uploaded files. `website` and `webpage` are user-created via this API."},"name":{"type":"string"},"connector_id":{"type":"string","nullable":true},"connector_type":{"type":"string","nullable":true},"sync_status":{"type":"string","description":"`ready`, `fetching`, `syncing`, `error`."},"last_sync_at":{"type":"string","format":"date-time","nullable":true},"document_count":{"type":"integer","nullable":true},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"SourceCreate":{"type":"object","required":["type","name"],"properties":{"type":{"type":"string","enum":["website","webpage"],"description":"Only `website` and `webpage` are user-creatable. `upload` is a per-org singleton already provisioned for you (POSTing it returns 409). `connector` is auto-created when the integration is added, POSTing it returns 422."},"name":{"type":"string","description":"Display name shown in the dashboard."},"config":{"type":"object","description":"Type-specific config. For `website` and `webpage`, include `url`. Indexed sources accept `indexed: true`.","properties":{"url":{"type":"string","description":"Required for website/webpage sources."},"indexed":{"type":"boolean","description":"When true, the source content is chunked + embedded and becomes searchable via `search_knowledge`. Defaults to false."}},"additionalProperties":true}}},"Chatbot":{"type":"object","required":["id","public_id","name","is_active","allow_write_tools","allowed_domains"],"properties":{"id":{"type":"string"},"public_id":{"type":"string","description":"Widget identifier embedded in customer sites. Safe to expose."},"name":{"type":"string"},"agent_id":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"allow_write_tools":{"type":"boolean"},"allowed_domains":{"type":"array","items":{"type":"string"}},"theme":{"type":"object","nullable":true,"additionalProperties":true},"welcome_message":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Trigger":{"type":"object","required":["id","connector_type","event","is_active"],"properties":{"id":{"type":"string"},"agent_id":{"type":"string","nullable":true},"connector_id":{"type":"string","nullable":true,"description":"`null` for Macha custom and cron-scheduled triggers."},"connector_type":{"type":"string"},"event":{"type":"string","description":"e.g. `ticket.created`, `cron.scheduled`, `macha.custom_trigger`."},"is_active":{"type":"boolean"},"conditions":{"type":"object","nullable":true,"additionalProperties":true},"settings":{"type":"object","additionalProperties":true},"schedule":{"type":"object","nullable":true,"description":"Set only for `cron.scheduled` triggers.","properties":{"cron_expression":{"type":"string","nullable":true},"interval_hours":{"type":"integer","nullable":true},"next_run_at":{"type":"string","format":"date-time","nullable":true},"last_run_at":{"type":"string","format":"date-time","nullable":true},"last_run_status":{"type":"string","nullable":true}}},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Member":{"type":"object","required":["id","user_id","email","role","is_active"],"properties":{"id":{"type":"string"},"user_id":{"type":"string"},"name":{"type":"string","nullable":true},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["owner","admin","member"]},"is_active":{"type":"boolean"},"last_login_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"Org":{"type":"object","required":["id","name","slug","plan","status","credits","limits"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"plan":{"type":"string","example":"pro"},"status":{"type":"string"},"credits":{"type":"object","required":["total","used","remaining"],"properties":{"total":{"type":"integer","minimum":0},"used":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0},"top_up":{"type":"integer","minimum":0},"reset_at":{"type":"string","format":"date-time","nullable":true}}},"limits":{"type":"object","description":"Per-plan resource caps. `null` means unlimited.","properties":{"agents":{"type":"integer","nullable":true},"connectors":{"type":"integer","nullable":true},"sources":{"type":"integer","nullable":true},"chatbots":{"type":"integer","nullable":true},"scheduled_triggers":{"type":"integer","nullable":true},"custom_tool_slots":{"type":"integer","nullable":true}}},"trial":{"type":"object","nullable":true,"properties":{"start_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true}}},"created_at":{"type":"string","format":"date-time","nullable":true}}}}}}