> ## 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 https://api.getcargo.io/INSTALL.md` 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. # Connect repository > Connect a GitHub repository to this project, so Cargo plans its pull requests and deploys its production branch as a service user. Refused unless the Cargo GitHub app is installed on the repository and the workspace's GitHub account administers it, when the project is already connected, and when that repository directory is connected elsewhere. (POST /workspaceManagement/states/{uuid}/connection). ## OpenAPI ````yaml https://api.getcargo.io/openapi.json post /workspaceManagement/states/{uuid}/connection 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: /workspaceManagement/states/{uuid}/connection: post: tags: - Workspace Management - States summary: Connect repository description: >- Connect a GitHub repository to this project, so Cargo plans its pull requests and deploys its production branch as a service user. Refused unless the Cargo GitHub app is installed on the repository and the workspace's GitHub account administers it, when the project is already connected, and when that repository directory is connected elsewhere. (POST /workspaceManagement/states/{uuid}/connection). operationId: postWorkspaceManagementStatesByUuidConnection parameters: - in: path name: uuid schema: type: string title: State UUID description: Project to connect a repository to. required: true description: Project to connect a repository to. - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object properties: githubOwner: type: string minLength: 1 maxLength: 255 title: GitHub owner description: Owner of the repository to connect. githubRepo: type: string minLength: 1 maxLength: 255 title: GitHub repo description: Repository to connect. connectorUuid: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ title: Connector UUID description: >- The workspace's GitHub connector. Its account must be an admin of the repository. directory: title: Directory description: >- Project directory inside the repository. Defaults to the repository root. type: string maxLength: 1024 productionBranch: type: string minLength: 1 maxLength: 255 title: Production branch description: Pushes to this branch deploy. Every other branch only plans. autoDeploy: title: Auto deploy description: >- Whether pushes to the production branch deploy. Pull requests are planned either way. Defaults to true. type: boolean runAsUserUuid: title: Run as user UUID description: >- Service user a deploy runs as, whose permissions must be covered by the caller's. Each deploy gets a temporary CARGO_API_TOKEN for that user. Without one, a service user is created for this repository with the caller's permissions. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - githubOwner - githubRepo - connectorUuid - productionBranch additionalProperties: false title: Request body description: Request body schema. responses: '200': description: Connect repository 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: state: type: object properties: uuid: type: string description: State identifier. workspaceUuid: type: string description: Workspace this state belongs to. githubOwner: anyOf: - type: string - type: 'null' description: >- GitHub owner of the repo this state was created from, if known. githubRepo: anyOf: - type: string - type: 'null' description: GitHub repo this state was created from, if known. defaultBranch: anyOf: - type: string - type: 'null' description: Default branch of that repo, if known. connection: anyOf: - type: object properties: directory: type: string description: >- Project directory inside the repository, '.' at the root. productionBranch: type: string description: >- Pushes to this branch deploy; every other branch only plans. autoDeploy: type: boolean description: >- Whether pushes to the production branch deploy. Pull requests are planned either way. userUuid: type: string description: User who connected this repository. runAsUserUuid: type: string description: >- Service user a deploy's temporary token acts as. Created for the repository when connecting does not name one. createdAt: description: Time this repository was connected. type: string required: - directory - productionBranch - autoDeploy - userUuid - runAsUserUuid - createdAt additionalProperties: false - type: 'null' description: >- The connected repository Cargo plans and deploys, or null when none is connected. contents: type: object propertyNames: type: string additionalProperties: {} description: Current deploy state. previousContents: anyOf: - type: object propertyNames: type: string additionalProperties: {} description: Deploy state blob written by the CDK. - type: 'null' description: >- Deploy state before the last snapshotted write, for rollback. contentsVersion: type: number description: >- Version of the stored contents, incremented on every write. Send the version you read to detect a concurrent change. lock: anyOf: - type: object properties: holderId: type: string description: Identifier of the run holding this lock. host: type: string description: Machine the holding run is on. command: type: string description: Command the holding run is executing. acquiredAt: description: Time this lock was taken. type: string expiresAt: description: >- Time after which another run may steal this lock. type: string required: - holderId - host - command - acquiredAt - expiresAt additionalProperties: false - type: 'null' description: The run currently allowed to write this state, if any. createdAt: description: Time this state was created. type: string updatedAt: description: Time this state was last written. type: string deletedAt: anyOf: - type: string - type: 'null' description: Time this state was deleted, if it has been. required: - uuid - workspaceUuid - githubOwner - githubRepo - defaultBranch - connection - contents - previousContents - contentsVersion - lock - createdAt - updatedAt - deletedAt additionalProperties: false required: - state 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.