> ## 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. # Mint harness proxy token > Mint a temporary Anthropic proxy token for a local Claude Code harness turn. Credit-checks the workspace first. Does not provision a sandbox. (POST /ai/chats/{uuid}/harness-proxy-token). ## OpenAPI ````yaml https://api.getcargo.io/openapi.json post /ai/chats/{uuid}/harness-proxy-token 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/chats/{uuid}/harness-proxy-token: post: tags: - AI - Chats summary: Mint harness proxy token description: >- Mint a temporary Anthropic proxy token for a local Claude Code harness turn. Credit-checks the workspace first. Does not provision a sandbox. (POST /ai/chats/{uuid}/harness-proxy-token). operationId: postAiChatsByUuidHarnessProxyToken parameters: - in: path name: uuid schema: 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: UUID description: Chat identifier. required: true description: Chat identifier. - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Mint harness proxy token 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: token: type: string title: Token description: Temporary Anthropic proxy token for this chat. expiresInSeconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 title: Expires in seconds description: Sliding TTL of the minted token. required: - token - expiresInSeconds 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. ````