> ## Documentation Index > Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually. > The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles. > Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up. > Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate. # Ingest local harness messages > Persist a finished user turn and assistant turn from a local Claude Code harness. Does not start a Temporal workflow or stream. (POST /ai/messages/ingest). ## OpenAPI ````yaml https://api.getcargo.io/openapi.json post /ai/messages/ingest openapi: 3.1.0 info: title: Cargo API version: 1.0.0 description: >- Cargo Platform API v1. ## Authentication Every endpoint requires a bearer token: `Authorization: Bearer `. There is no unauthenticated endpoint. Create a token with `cargo-ai login`, or complete OAuth 2.0 authorization code with PKCE (the `oauth2` scheme). Authorization-server metadata (RFC 8414) is at `https://getcargo.eu.auth0.com/.well-known/oauth-authorization-server`. ## Errors Every 4xx and 5xx response uses the shared `Error` schema: a JSON object carrying `errorMessage`, a human-readable description of what went wrong. A long tail of orchestration routes carries `reason` instead, a machine-readable cause. Routes may add fields (`retryAfter` on a 429), so treat the object as open rather than closed. ## Rate limits Requests are counted per workspace. Every `/v1` response, including the 401 an unauthenticated caller gets, carries `RateLimit` (`"workspace";r=;t=`), `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`, and the legacy `X-RateLimit-*` spellings alongside them. A 429 carries `Retry-After` in seconds: back off by that, rather than retrying immediately. ## Idempotency POST, PUT and PATCH accept an optional `Idempotency-Key` header. A retry with the same key and the same request returns the original response instead of creating a second record. Reusing a key with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Multipart file uploads do not accept the header: the body is not parsed until after the key would have to be fingerprinted. ## Versioning and deprecation The version is in the path (`/v1`), and a breaking change ships as a new path rather than by altering this one. Adding a field to a response, a new optional request field, or a new endpoint is not breaking, so a client must ignore fields it does not recognise. The deprecation policy is at https://docs.getcargo.ai/api-reference/versioning. When an endpoint is being retired it carries the `Deprecation` header (RFC 9745) and, once a removal date is fixed, `Sunset` (RFC 8594). Both are HTTP dates. There are at least 180 days between them. An endpoint marked `deprecated` in this document is still served until its `Sunset` passes. No `/v1` operation is currently deprecated. ## Long-running operations Creating a run or a batch does not wait for the work to finish. The create request returns `202 Accepted` with a `Location` header pointing at the run or batch. Poll that URL (or `GET` the run / batch by `uuid`) until it reaches a terminal status (`success`, `error`, `cancelled`, or `skipped`). Do not retry the create request while the job is still running. Action execute endpoints follow the same pattern unless `waitUntilFinished` is true, in which case a finished job is `200`. servers: - url: https://api.getcargo.io/v1 description: Cargo API security: - bearerAuth: [] - oauth2: - openid - profile - email - offline_access externalDocs: description: API versioning and deprecation policy url: https://docs.getcargo.ai/api-reference/versioning paths: /ai/messages/ingest: post: tags: - AI - Messages summary: Ingest local harness messages description: >- Persist a finished user turn and assistant turn from a local Claude Code harness. Does not start a Temporal workflow or stream. (POST /ai/messages/ingest). operationId: postAiMessagesIngest parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object properties: chatUuid: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$ title: Chat UUID description: Chat identifier. agentUuid: title: Agent UUID description: Agent identifier for the ingested messages. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$ userParts: type: array items: {} title: User parts description: Finished user message parts. assistantParts: type: array items: {} title: Assistant parts description: Finished assistant message parts. turnOwnerId: title: Turn owner id description: >- The id this caller claimed the chat with. Recording the turn releases that claim, and only that one. type: string minLength: 1 maxLength: 255 cancelled: title: Cancelled description: >- True when the turn was interrupted. It is still recorded, since the tokens were spent, but stored as cancelled rather than as a finished answer. type: boolean usage: title: Usage description: Usage recorded on the assistant message, if any. type: object properties: costUsd: type: number minimum: 0 maximum: 100 totalTokens: type: number minimum: 0 inputTokens: type: number minimum: 0 outputTokens: type: number minimum: 0 cacheReadTokens: type: number minimum: 0 cacheWriteTokens: type: number minimum: 0 reasoningTokens: type: number minimum: 0 additionalProperties: false required: - chatUuid - userParts - assistantParts additionalProperties: false title: Request body description: Request body schema. responses: '200': description: Ingest local harness messages headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: type: object properties: userMessage: type: object properties: uuid: type: string description: Message identifier. workspaceUuid: type: string description: Workspace this message belongs to. agentUuid: anyOf: - type: string - type: 'null' description: Agent that produced this message, if any. releaseUuid: anyOf: - type: string - type: 'null' description: Release used to generate this message, if any. chatUuid: type: string description: Chat this message belongs to. userUuid: anyOf: - type: string - type: 'null' description: User who sent this message, if any. status: type: string enum: - pending - generating - success - error - cancelling - cancelled description: Current generation status of this message. errorMessage: anyOf: - type: string - type: 'null' description: Error from a failed generation, if any. type: type: string enum: - user - assistant description: >- Whether this message is from the user or the assistant. parts: type: array items: {} description: Message parts such as text and tool calls. actions: type: array items: allOf: - type: object properties: name: anyOf: - type: string - type: 'null' description: Action display name, if set. slug: type: string description: Stable slug that identifies this action. description: anyOf: - type: string - type: 'null' description: What this action does, if set. isBulkAllowed: type: boolean description: >- Whether this action can run on many records at once. config: type: object propertyNames: type: string additionalProperties: {} description: Action-specific configuration. required: - name - slug - description - isBulkAllowed - config additionalProperties: false - anyOf: - type: object properties: kind: type: string description: Action invokes a workspace tool. enum: - tool toolUuid: anyOf: - type: string - type: 'null' description: Tool this action invokes, if bound. templateSlug: anyOf: - type: string - type: 'null' description: >- Template this tool was created from, if any. waitUntilFinished: type: boolean description: >- Whether the caller waits for the tool to finish. required: - kind - toolUuid - templateSlug - waitUntilFinished additionalProperties: false - type: object properties: kind: type: string description: Action invokes another agent. enum: - agent agentUuid: anyOf: - type: string - type: 'null' description: Agent this action invokes, if bound. templateSlug: anyOf: - type: string - type: 'null' description: >- Template this agent was created from, if any. waitUntilFinished: type: boolean description: >- Whether the caller waits for the agent to finish. required: - kind - agentUuid - templateSlug - waitUntilFinished additionalProperties: false - type: object properties: kind: type: string description: Action calls a connector integration. enum: - connector integrationSlug: type: string description: Integration that defines this action. connectorUuid: anyOf: - type: string - type: 'null' description: Connector this action calls, if bound. actionSlug: type: string description: Slug of the connector action to run. required: - kind - integrationSlug - connectorUuid - actionSlug additionalProperties: false - type: object properties: kind: type: string description: Action is a built-in Cargo action. enum: - native actionSlug: type: string description: Slug of the native action to run. required: - kind - actionSlug additionalProperties: false description: Actions available while generating this message. resources: type: array items: anyOf: - type: object properties: kind: type: string description: Resource exposes a workspace model. enum: - model name: anyOf: - type: string - type: 'null' description: Resource display name, if set. slug: type: string description: Stable slug that identifies this resource. description: anyOf: - type: string - type: 'null' description: What this resource is for, if set. prompt: anyOf: - type: string - type: 'null' description: >- Instructions for how the agent should use this model. integrationSlug: anyOf: - type: string - type: 'null' description: Integration that backs this model, if any. modelUuid: anyOf: - type: string - type: 'null' description: Model this resource exposes, if bound. filter: anyOf: - type: object properties: conjonction: type: string enum: - or - and description: How groups in this filter are combined. groups: type: array items: {} description: >- Groups of conditions that make up this filter. required: - conjonction - groups additionalProperties: false - type: 'null' description: >- Filter that limits which records the agent may read. selectedColumnSlugs: anyOf: - type: array items: type: string - type: 'null' description: >- Model columns the agent may read, if restricted. limit: anyOf: - type: number - type: 'null' description: >- Maximum number of records the agent may read. isReadOnly: type: boolean description: Whether the agent may only read this model. required: - kind - name - slug - description - prompt - integrationSlug - modelUuid - filter - selectedColumnSlugs - limit - isReadOnly additionalProperties: false - type: object properties: kind: type: string description: Resource exposes files and folders. enum: - file name: anyOf: - type: string - type: 'null' description: Resource display name, if set. slug: type: string description: Stable slug that identifies this resource. description: anyOf: - type: string - type: 'null' description: What this resource is for, if set. prompt: anyOf: - type: string - type: 'null' description: >- Instructions for how the agent should use these files. items: type: array items: anyOf: - type: object properties: kind: type: string description: Selection is a single file. enum: - file fileUuid: type: string description: File this selection points to. required: - kind - fileUuid additionalProperties: false - type: object properties: kind: type: string description: Selection is a folder of files. enum: - folder folderUuid: type: string description: Folder this selection points to. required: - kind - folderUuid additionalProperties: false description: Files and folders this resource exposes. required: - kind - name - slug - description - prompt - items additionalProperties: false description: Resources available while generating this message. capabilities: type: array items: oneOf: - type: object properties: slug: type: string description: Capability grants a code sandbox. enum: - sandbox config: type: object properties: scope: description: >- Surface this sandbox is available on, if restricted. type: string enum: - chat - agent additionalProperties: false description: Sandbox-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants workspace context. enum: - context config: type: object properties: isReadOnly: description: >- Whether context may only be read, not written. type: boolean additionalProperties: false description: Context-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants access to a Cargo app. enum: - app config: type: object properties: appUuid: description: >- App this capability is scoped to, if any. type: string canPromote: description: >- Whether the agent may promote work into this app. type: boolean additionalProperties: false description: App-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants document read and write. enum: - document config: type: object propertyNames: type: string additionalProperties: {} description: Document-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants web search. enum: - webSearch config: type: object propertyNames: type: string additionalProperties: {} description: Web-search configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants model read and write. enum: - model config: type: object propertyNames: type: string additionalProperties: {} description: Model-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants file read and write. enum: - file config: type: object propertyNames: type: string additionalProperties: {} description: File-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants documentation search. enum: - documentationSearch config: type: object propertyNames: type: string additionalProperties: {} description: Documentation-search configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants long-term memory. enum: - memory config: type: object propertyNames: type: string additionalProperties: {} description: Memory-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants suggested next actions. enum: - suggestedActions config: type: object propertyNames: type: string additionalProperties: {} description: Suggested-actions configuration. required: - slug - config additionalProperties: false type: object description: Capabilities available while generating this message. mcpClients: type: array items: oneOf: - type: object properties: kind: type: string description: MCP client talks to a custom server URL. enum: - custom name: type: string description: Display name of this MCP client. url: type: string description: URL of the custom MCP server. authentication: anyOf: - type: object properties: issuedAt: type: string description: Time the access token was issued. accessToken: type: string description: OAuth access token. expiresIn: description: >- Access-token lifetime in seconds, if provided. type: number refreshToken: description: OAuth refresh token, if issued. type: string scope: description: >- OAuth scopes granted to this token, if provided. type: string tokenType: description: OAuth token type, if provided. type: string clientId: description: OAuth client identifier, if stored. type: string clientSecret: description: OAuth client secret, if stored. type: string required: - issuedAt - accessToken additionalProperties: false - type: 'null' description: >- OAuth tokens used to call the server, if any. disabledToolSlugs: type: array items: type: string description: MCP tools that are hidden from the agent. required: - kind - name - url - authentication - disabledToolSlugs additionalProperties: false - type: object properties: kind: type: string description: MCP client is backed by a Cargo connector. enum: - connector name: type: string description: Display name of this MCP client. connectorUuid: type: string description: Connector that hosts this MCP server. integrationSlug: type: string description: Integration that defines this MCP client. disabledToolSlugs: type: array items: type: string description: MCP tools that are hidden from the agent. required: - kind - name - connectorUuid - integrationSlug - disabledToolSlugs additionalProperties: false type: object description: MCP clients available while generating this message. systemPrompt: anyOf: - type: string - type: 'null' description: System prompt used for this message, if set. withReasoning: anyOf: - type: boolean - type: 'null' description: Whether the model was asked to reason, if set. temperature: anyOf: - type: number - type: 'null' description: Sampling temperature used for this message, if set. maxSteps: anyOf: - type: number - type: 'null' description: >- Maximum tool-calling steps allowed for this message, if set. integrationSlug: anyOf: - type: string - type: 'null' description: LLM integration used for this message, if set. connectorUuid: anyOf: - type: string - type: 'null' description: Connector used for the language model, if any. languageModelSlug: anyOf: - type: string - type: 'null' description: Language model used for this message, if set. evaluatedTools: type: object propertyNames: type: string additionalProperties: {} description: >- Tool invocations evaluated while generating this message. usage: anyOf: - type: object properties: tokensUsedCount: type: number description: Tokens consumed by this message. creditsUsedCount: type: number description: Credits consumed by this message. languageModelSlug: type: string description: Language model that generated this message. connectorUuid: type: string description: Connector used for the language model. required: - tokensUsedCount - creditsUsedCount - languageModelSlug - connectorUuid additionalProperties: false - type: 'null' description: Token and credit usage for this message, if recorded. output: description: Structured output produced by this message, if any. meta: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: Additional metadata for this message, if any. suggestedActions: type: array items: type: object properties: text: type: string description: Suggested prompt shown to the user. actions: type: array items: type: object properties: slug: type: string description: >- Action to run when this suggestion is chosen. required: - slug additionalProperties: false description: Actions the suggestion will run. required: - text - actions additionalProperties: false description: Suggested next actions after this message. temporalWorkflowId: anyOf: - type: string - type: 'null' description: Temporal workflow generating this message, if any. createdAt: description: Time this message was created. type: string updatedAt: description: Time this message was last updated. type: string finishedAt: anyOf: - type: string - type: 'null' description: Time generation finished, if it has. deletedAt: anyOf: - type: string - type: 'null' description: Time this message was deleted, if it has been. required: - uuid - workspaceUuid - agentUuid - releaseUuid - chatUuid - userUuid - status - errorMessage - type - parts - actions - resources - capabilities - mcpClients - systemPrompt - withReasoning - temperature - maxSteps - integrationSlug - connectorUuid - languageModelSlug - evaluatedTools - usage - output - meta - suggestedActions - temporalWorkflowId - createdAt - updatedAt - finishedAt - deletedAt additionalProperties: false title: User message description: The ingested user message. assistantMessage: type: object properties: uuid: type: string description: Message identifier. workspaceUuid: type: string description: Workspace this message belongs to. agentUuid: anyOf: - type: string - type: 'null' description: Agent that produced this message, if any. releaseUuid: anyOf: - type: string - type: 'null' description: Release used to generate this message, if any. chatUuid: type: string description: Chat this message belongs to. userUuid: anyOf: - type: string - type: 'null' description: User who sent this message, if any. status: type: string enum: - pending - generating - success - error - cancelling - cancelled description: Current generation status of this message. errorMessage: anyOf: - type: string - type: 'null' description: Error from a failed generation, if any. type: type: string enum: - user - assistant description: >- Whether this message is from the user or the assistant. parts: type: array items: {} description: Message parts such as text and tool calls. actions: type: array items: allOf: - type: object properties: name: anyOf: - type: string - type: 'null' description: Action display name, if set. slug: type: string description: Stable slug that identifies this action. description: anyOf: - type: string - type: 'null' description: What this action does, if set. isBulkAllowed: type: boolean description: >- Whether this action can run on many records at once. config: type: object propertyNames: type: string additionalProperties: {} description: Action-specific configuration. required: - name - slug - description - isBulkAllowed - config additionalProperties: false - anyOf: - type: object properties: kind: type: string description: Action invokes a workspace tool. enum: - tool toolUuid: anyOf: - type: string - type: 'null' description: Tool this action invokes, if bound. templateSlug: anyOf: - type: string - type: 'null' description: >- Template this tool was created from, if any. waitUntilFinished: type: boolean description: >- Whether the caller waits for the tool to finish. required: - kind - toolUuid - templateSlug - waitUntilFinished additionalProperties: false - type: object properties: kind: type: string description: Action invokes another agent. enum: - agent agentUuid: anyOf: - type: string - type: 'null' description: Agent this action invokes, if bound. templateSlug: anyOf: - type: string - type: 'null' description: >- Template this agent was created from, if any. waitUntilFinished: type: boolean description: >- Whether the caller waits for the agent to finish. required: - kind - agentUuid - templateSlug - waitUntilFinished additionalProperties: false - type: object properties: kind: type: string description: Action calls a connector integration. enum: - connector integrationSlug: type: string description: Integration that defines this action. connectorUuid: anyOf: - type: string - type: 'null' description: Connector this action calls, if bound. actionSlug: type: string description: Slug of the connector action to run. required: - kind - integrationSlug - connectorUuid - actionSlug additionalProperties: false - type: object properties: kind: type: string description: Action is a built-in Cargo action. enum: - native actionSlug: type: string description: Slug of the native action to run. required: - kind - actionSlug additionalProperties: false description: Actions available while generating this message. resources: type: array items: anyOf: - type: object properties: kind: type: string description: Resource exposes a workspace model. enum: - model name: anyOf: - type: string - type: 'null' description: Resource display name, if set. slug: type: string description: Stable slug that identifies this resource. description: anyOf: - type: string - type: 'null' description: What this resource is for, if set. prompt: anyOf: - type: string - type: 'null' description: >- Instructions for how the agent should use this model. integrationSlug: anyOf: - type: string - type: 'null' description: Integration that backs this model, if any. modelUuid: anyOf: - type: string - type: 'null' description: Model this resource exposes, if bound. filter: anyOf: - type: object properties: conjonction: type: string enum: - or - and description: How groups in this filter are combined. groups: type: array items: {} description: >- Groups of conditions that make up this filter. required: - conjonction - groups additionalProperties: false - type: 'null' description: >- Filter that limits which records the agent may read. selectedColumnSlugs: anyOf: - type: array items: type: string - type: 'null' description: >- Model columns the agent may read, if restricted. limit: anyOf: - type: number - type: 'null' description: >- Maximum number of records the agent may read. isReadOnly: type: boolean description: Whether the agent may only read this model. required: - kind - name - slug - description - prompt - integrationSlug - modelUuid - filter - selectedColumnSlugs - limit - isReadOnly additionalProperties: false - type: object properties: kind: type: string description: Resource exposes files and folders. enum: - file name: anyOf: - type: string - type: 'null' description: Resource display name, if set. slug: type: string description: Stable slug that identifies this resource. description: anyOf: - type: string - type: 'null' description: What this resource is for, if set. prompt: anyOf: - type: string - type: 'null' description: >- Instructions for how the agent should use these files. items: type: array items: anyOf: - type: object properties: kind: type: string description: Selection is a single file. enum: - file fileUuid: type: string description: File this selection points to. required: - kind - fileUuid additionalProperties: false - type: object properties: kind: type: string description: Selection is a folder of files. enum: - folder folderUuid: type: string description: Folder this selection points to. required: - kind - folderUuid additionalProperties: false description: Files and folders this resource exposes. required: - kind - name - slug - description - prompt - items additionalProperties: false description: Resources available while generating this message. capabilities: type: array items: oneOf: - type: object properties: slug: type: string description: Capability grants a code sandbox. enum: - sandbox config: type: object properties: scope: description: >- Surface this sandbox is available on, if restricted. type: string enum: - chat - agent additionalProperties: false description: Sandbox-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants workspace context. enum: - context config: type: object properties: isReadOnly: description: >- Whether context may only be read, not written. type: boolean additionalProperties: false description: Context-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants access to a Cargo app. enum: - app config: type: object properties: appUuid: description: >- App this capability is scoped to, if any. type: string canPromote: description: >- Whether the agent may promote work into this app. type: boolean additionalProperties: false description: App-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants document read and write. enum: - document config: type: object propertyNames: type: string additionalProperties: {} description: Document-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants web search. enum: - webSearch config: type: object propertyNames: type: string additionalProperties: {} description: Web-search configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants model read and write. enum: - model config: type: object propertyNames: type: string additionalProperties: {} description: Model-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants file read and write. enum: - file config: type: object propertyNames: type: string additionalProperties: {} description: File-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants documentation search. enum: - documentationSearch config: type: object propertyNames: type: string additionalProperties: {} description: Documentation-search configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants long-term memory. enum: - memory config: type: object propertyNames: type: string additionalProperties: {} description: Memory-specific configuration. required: - slug - config additionalProperties: false - type: object properties: slug: type: string description: Capability grants suggested next actions. enum: - suggestedActions config: type: object propertyNames: type: string additionalProperties: {} description: Suggested-actions configuration. required: - slug - config additionalProperties: false type: object description: Capabilities available while generating this message. mcpClients: type: array items: oneOf: - type: object properties: kind: type: string description: MCP client talks to a custom server URL. enum: - custom name: type: string description: Display name of this MCP client. url: type: string description: URL of the custom MCP server. authentication: anyOf: - type: object properties: issuedAt: type: string description: Time the access token was issued. accessToken: type: string description: OAuth access token. expiresIn: description: >- Access-token lifetime in seconds, if provided. type: number refreshToken: description: OAuth refresh token, if issued. type: string scope: description: >- OAuth scopes granted to this token, if provided. type: string tokenType: description: OAuth token type, if provided. type: string clientId: description: OAuth client identifier, if stored. type: string clientSecret: description: OAuth client secret, if stored. type: string required: - issuedAt - accessToken additionalProperties: false - type: 'null' description: >- OAuth tokens used to call the server, if any. disabledToolSlugs: type: array items: type: string description: MCP tools that are hidden from the agent. required: - kind - name - url - authentication - disabledToolSlugs additionalProperties: false - type: object properties: kind: type: string description: MCP client is backed by a Cargo connector. enum: - connector name: type: string description: Display name of this MCP client. connectorUuid: type: string description: Connector that hosts this MCP server. integrationSlug: type: string description: Integration that defines this MCP client. disabledToolSlugs: type: array items: type: string description: MCP tools that are hidden from the agent. required: - kind - name - connectorUuid - integrationSlug - disabledToolSlugs additionalProperties: false type: object description: MCP clients available while generating this message. systemPrompt: anyOf: - type: string - type: 'null' description: System prompt used for this message, if set. withReasoning: anyOf: - type: boolean - type: 'null' description: Whether the model was asked to reason, if set. temperature: anyOf: - type: number - type: 'null' description: Sampling temperature used for this message, if set. maxSteps: anyOf: - type: number - type: 'null' description: >- Maximum tool-calling steps allowed for this message, if set. integrationSlug: anyOf: - type: string - type: 'null' description: LLM integration used for this message, if set. connectorUuid: anyOf: - type: string - type: 'null' description: Connector used for the language model, if any. languageModelSlug: anyOf: - type: string - type: 'null' description: Language model used for this message, if set. evaluatedTools: type: object propertyNames: type: string additionalProperties: {} description: >- Tool invocations evaluated while generating this message. usage: anyOf: - type: object properties: tokensUsedCount: type: number description: Tokens consumed by this message. creditsUsedCount: type: number description: Credits consumed by this message. languageModelSlug: type: string description: Language model that generated this message. connectorUuid: type: string description: Connector used for the language model. required: - tokensUsedCount - creditsUsedCount - languageModelSlug - connectorUuid additionalProperties: false - type: 'null' description: Token and credit usage for this message, if recorded. output: description: Structured output produced by this message, if any. meta: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: Additional metadata for this message, if any. suggestedActions: type: array items: type: object properties: text: type: string description: Suggested prompt shown to the user. actions: type: array items: type: object properties: slug: type: string description: >- Action to run when this suggestion is chosen. required: - slug additionalProperties: false description: Actions the suggestion will run. required: - text - actions additionalProperties: false description: Suggested next actions after this message. temporalWorkflowId: anyOf: - type: string - type: 'null' description: Temporal workflow generating this message, if any. createdAt: description: Time this message was created. type: string updatedAt: description: Time this message was last updated. type: string finishedAt: anyOf: - type: string - type: 'null' description: Time generation finished, if it has. deletedAt: anyOf: - type: string - type: 'null' description: Time this message was deleted, if it has been. required: - uuid - workspaceUuid - agentUuid - releaseUuid - chatUuid - userUuid - status - errorMessage - type - parts - actions - resources - capabilities - mcpClients - systemPrompt - withReasoning - temperature - maxSteps - integrationSlug - connectorUuid - languageModelSlug - evaluatedTools - usage - output - meta - suggestedActions - temporalWorkflowId - createdAt - updatedAt - finishedAt - deletedAt additionalProperties: false title: Assistant message description: The ingested assistant message. required: - userMessage - assistantMessage additionalProperties: false '400': $ref: '#/components/responses/BadRequest' content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' content: application/json: schema: $ref: '#/components/schemas/Error' '404': $ref: '#/components/responses/NotFound' content: application/json: schema: $ref: '#/components/schemas/Error' '409': $ref: '#/components/responses/Conflict' content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/UnprocessableEntity' content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/TooManyRequests' content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: IdempotencyKey: in: header name: Idempotency-Key schema: description: >- Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was. example: 8e03978e-40d5-43e8-bc93-6894a57f9324 type: string maxLength: 255 description: >- Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was. responses: BadRequest: description: Bad request headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: A request with this Idempotency-Key is already in progress. headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: Idempotency-Key was reused with a different request. headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: >- Too many requests. Retry after the number of seconds in the Retry-After header. headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal server error headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object properties: errorMessage: description: Human-readable description of what went wrong. type: string reason: description: >- Machine-readable cause, used where a route distinguishes failure modes. type: string additionalProperties: {} description: Error response securitySchemes: bearerAuth: type: http scheme: bearer description: >- API token from `cargo-ai login`. Send as `Authorization: Bearer `. oauth2: type: oauth2 description: >- OAuth 2.0 authorization code with PKCE (S256). Discover endpoints from https://getcargo.eu.auth0.com/.well-known/oauth-authorization-server. Include `audience=https://api.getcargo.io` in the authorization request to obtain a JWT valid for this API. flows: authorizationCode: authorizationUrl: https://getcargo.eu.auth0.com/authorize tokenUrl: https://getcargo.eu.auth0.com/oauth/token scopes: openid: OpenID Connect identity. profile: Name and profile claims. email: Email address. offline_access: Refresh token. ````