> ## 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, valid for its first 30 days, 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 this project's repository (the one the state names) to Cargo, 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 through an installation linked to this workspace, except in Cargo's managed org, where the repository is the one Cargo created for this project. Refused when the project has no repository or production branch, when it 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 <token>`.

    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=<remaining>;t=<window seconds>`), `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 this project's repository (the one the state names) to Cargo, 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 through an installation linked to this workspace, except in
        Cargo's managed org, where the repository is the one Cargo created for
        this project. Refused when the project has no repository or production
        branch, when it 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:
                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)$
              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=<remaining>;t=<window seconds>`.
              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 `<limit>;w=<window seconds>`.
              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.
                      gitProvider:
                        type: string
                        enum:
                          - github
                        description: Where the repository this project lives in is hosted.
                      gitOwner:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: >-
                          Owner of the repository this project lives in, if
                          known.
                      gitRepo:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Repository this project lives in, if known.
                      directory:
                        type: string
                        description: >-
                          Project directory inside the repository, '.' at the
                          root.
                      productionBranch:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: >-
                          Pushes to this branch deploy once connected; every
                          other branch only plans.
                      isManaged:
                        type: boolean
                        description: >-
                          Whether Cargo created and holds this project's
                          repository. A managed project stays connected, and
                          deleting it archives the repository.
                      connection:
                        anyOf:
                          - type: object
                            properties:
                              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.
                              gitRepositoryId:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  The provider's id for the repository, which
                                  survives a rename or transfer. Null on an
                                  older connection until a rename or transfer of
                                  its repository fills it.
                              gitAccountId:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  The provider's id for the account the
                                  repository is reached through (on GitHub, the
                                  Cargo app's installation). Null on an older
                                  connection until a rename or transfer of its
                                  repository fills it.
                              createdAt:
                                description: Time this repository was connected.
                                type: string
                            required:
                              - autoDeploy
                              - userUuid
                              - runAsUserUuid
                              - gitRepositoryId
                              - gitAccountId
                              - createdAt
                            additionalProperties: false
                          - type: 'null'
                        description: >-
                          How Cargo runs the project's repository, or null when
                          it is not 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 `cargo-ai project`.
                          - type: 'null'
                        description: >-
                          Deploy state before the last snapshotted write, for
                          rollback.
                      meta:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                        description: >-
                          What apps built on Cargo keep about this project, each
                          under its own key. Deploys never change it.
                      endpoint:
                        anyOf:
                          - type: object
                            properties:
                              url:
                                type: string
                                format: uri
                                description: >-
                                  Where Cargo asks for the config of a chat to
                                  open.
                              triggers:
                                type: array
                                items:
                                  oneOf:
                                    - type: object
                                      properties:
                                        type:
                                          type: string
                                          description: A native agent's trigger.
                                          enum:
                                            - native
                                        agentSlug:
                                          type: string
                                          enum:
                                            - state
                                          description: >-
                                            The native agent: state, mentions of
                                            Cargo on pull requests of the connected
                                            repository.
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: >-
                                            The agent's trigger config, as on an
                                            agent's trigger.
                                      required:
                                        - type
                                        - agentSlug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        type:
                                          type: string
                                          description: A connector's trigger.
                                          enum:
                                            - connector
                                        connectorUuid:
                                          type: string
                                          minLength: 1
                                          description: >-
                                            The connector, in this workspace: Slack,
                                            the channels and direct messages to
                                            answer in.
                                        integrationSlug:
                                          type: string
                                          minLength: 1
                                          description: >-
                                            The connector's integration, such as
                                            slack.
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: >-
                                            The integration's trigger config, as on
                                            an agent's trigger (Slack: channelIds,
                                            allChannels).
                                      required:
                                        - type
                                        - connectorUuid
                                        - integrationSlug
                                        - config
                                      additionalProperties: false
                                  type: object
                                description: >-
                                  The triggers it takes, at most one per native
                                  agent and one per connector: an event one of
                                  them matches that no chat or agent holds gets
                                  a chat opened from the config the endpoint
                                  answers.
                            required:
                              - url
                              - triggers
                            additionalProperties: false
                          - type: 'null'
                        description: >-
                          Where Cargo asks for the config of the chats this
                          project answers with, and on which triggers, or null
                          when none.
                      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
                      - gitProvider
                      - gitOwner
                      - gitRepo
                      - directory
                      - productionBranch
                      - isManaged
                      - connection
                      - contents
                      - previousContents
                      - meta
                      - endpoint
                      - contentsVersion
                      - lock
                      - createdAt
                      - updatedAt
                      - deletedAt
                    additionalProperties: false
                  stateRun:
                    title: State run
                    description: >-
                      The deploy that connecting started on the production
                      branch, when the project auto-deploys.
                    type: object
                    properties:
                      uuid:
                        type: string
                        description: Run identifier.
                      workspaceUuid:
                        type: string
                        description: Workspace this run belongs to.
                      stateUuid:
                        type: string
                        description: Project this run planned or applied.
                      kind:
                        type: string
                        enum:
                          - plan
                          - deploy
                        description: Whether this run previewed a diff or applied one.
                      trigger:
                        type: string
                        enum:
                          - pullRequest
                          - push
                          - manual
                        description: What started this run.
                      status:
                        type: string
                        enum:
                          - queued
                          - running
                          - success
                          - error
                          - cancelled
                        description: >-
                          Run status. 'cancelled' means a newer commit arrived
                          before it finished.
                      headSha:
                        type: string
                        description: Commit this run was made from.
                      branch:
                        type: string
                        description: Branch this run was made from.
                      pullRequestNumber:
                        anyOf:
                          - type: number
                          - type: 'null'
                        description: Pull request this run reported on, if any.
                      summary:
                        anyOf:
                          - type: object
                            properties:
                              create:
                                type: number
                                description: Resources to create.
                              update:
                                type: number
                                description: Resources to update.
                              noop:
                                type: number
                                description: Resources already up to date.
                              delete:
                                type: number
                                description: >-
                                  Resources tracked in state but no longer in
                                  code.
                              resources:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      description: >-
                                        Resource id in the project's code,
                                        `kind:slug`.
                                    kind:
                                      type: string
                                      description: Resource kind.
                                    slug:
                                      type: string
                                      description: Resource slug.
                                    change:
                                      type: string
                                      enum:
                                        - create
                                        - update
                                        - noop
                                        - delete
                                      description: >-
                                        What the run would do, or did, to this
                                        resource.
                                    name:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: Display name, when the resource has one.
                                    uuid:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                      description: >-
                                        Live resource uuid, when the state
                                        already knows one.
                                  required:
                                    - id
                                    - kind
                                    - slug
                                    - change
                                    - name
                                    - uuid
                                  additionalProperties: false
                                description: >-
                                  The resources that changed; unchanged ones are
                                  only counted.
                              impact:
                                anyOf:
                                  - type: object
                                    properties:
                                      entries:
                                        type: array
                                        items:
                                          anyOf:
                                            - type: object
                                              properties:
                                                kind:
                                                  type: string
                                                  description: A play the merge deploys.
                                                  enum:
                                                    - play
                                                id:
                                                  type: string
                                                  description: >-
                                                    Play id in the project's code,
                                                    `play:slug`.
                                                name:
                                                  anyOf:
                                                    - type: string
                                                    - type: 'null'
                                                  description: Play name.
                                                records:
                                                  anyOf:
                                                    - type: number
                                                    - type: 'null'
                                                  description: >-
                                                    Records it runs on: those entering a
                                                    play on deploy, or every record an
                                                    execution runs on. Null when they could
                                                    not be counted.
                                                effects:
                                                  type: array
                                                  items:
                                                    type: object
                                                    properties:
                                                      effect:
                                                        type: string
                                                        enum:
                                                          - email
                                                          - linkedin
                                                          - message
                                                          - audience
                                                        description: Kind of side effect.
                                                      count:
                                                        type: number
                                                        description: Upper bound on how many are sent.
                                                    required:
                                                      - effect
                                                      - count
                                                    additionalProperties: false
                                                  description: What its nodes send for those records.
                                                credits:
                                                  type: number
                                                  description: >-
                                                    Credits its connector actions spend for
                                                    those records.
                                                notes:
                                                  type: array
                                                  items:
                                                    type: string
                                                  description: What the estimate could not count.
                                              required:
                                                - kind
                                                - id
                                                - name
                                                - records
                                                - effects
                                                - credits
                                                - notes
                                              additionalProperties: false
                                            - type: object
                                              properties:
                                                kind:
                                                  type: string
                                                  enum:
                                                    - batch
                                                    - run
                                                  description: An execution the merge runs once.
                                                id:
                                                  type: string
                                                  description: Execution id in the project's code.
                                                hash:
                                                  anyOf:
                                                    - type: string
                                                    - type: 'null'
                                                  description: >-
                                                    Hash of the execution spec that was
                                                    counted; null when it did not read.
                                                workflow:
                                                  type: string
                                                  description: >-
                                                    Play or tool it runs, by name or slug,
                                                    or `inline`.
                                                maxRecords:
                                                  anyOf:
                                                    - type: number
                                                    - type: 'null'
                                                  description: >-
                                                    Most records the merge may find before
                                                    it holds the execution.
                                                records:
                                                  anyOf:
                                                    - type: number
                                                    - type: 'null'
                                                  description: >-
                                                    Records it runs on: those entering a
                                                    play on deploy, or every record an
                                                    execution runs on. Null when they could
                                                    not be counted.
                                                effects:
                                                  type: array
                                                  items:
                                                    type: object
                                                    properties:
                                                      effect:
                                                        type: string
                                                        enum:
                                                          - email
                                                          - linkedin
                                                          - message
                                                          - audience
                                                        description: Kind of side effect.
                                                      count:
                                                        type: number
                                                        description: Upper bound on how many are sent.
                                                    required:
                                                      - effect
                                                      - count
                                                    additionalProperties: false
                                                  description: What its nodes send for those records.
                                                credits:
                                                  type: number
                                                  description: >-
                                                    Credits its connector actions spend for
                                                    those records.
                                                notes:
                                                  type: array
                                                  items:
                                                    type: string
                                                  description: What the estimate could not count.
                                              required:
                                                - kind
                                                - id
                                                - hash
                                                - workflow
                                                - maxRecords
                                                - records
                                                - effects
                                                - credits
                                                - notes
                                              additionalProperties: false
                                        description: >-
                                          Every enabled play the run would change,
                                          then every pending execution the merge
                                          would run once.
                                      requiresApproval:
                                        type: boolean
                                        description: >-
                                          Whether the impact needs the approval
                                          label before the check passes.
                                      isApproved:
                                        type: boolean
                                        description: >-
                                          Whether the merge may set it in motion:
                                          no approval needed, or the label was
                                          there.
                                    required:
                                      - entries
                                      - requiresApproval
                                      - isApproved
                                    additionalProperties: false
                                  - type: 'null'
                                description: >-
                                  What merging would set in motion, when it was
                                  assessed.
                              executions:
                                type: array
                                items:
                                  anyOf:
                                    - type: object
                                      properties:
                                        id:
                                          type: string
                                          description: Execution id in the project's code.
                                        status:
                                          type: string
                                          description: Cargo started it.
                                          enum:
                                            - started
                                        batchUuid:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: The batch it started.
                                        runUuid:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: The run it started.
                                      required:
                                        - id
                                        - status
                                        - batchUuid
                                        - runUuid
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        id:
                                          type: string
                                          description: Execution id in the project's code.
                                        status:
                                          type: string
                                          description: Cargo refused to start it.
                                          enum:
                                            - refused
                                        errorMessage:
                                          type: string
                                          description: Why Cargo refused it.
                                      required:
                                        - id
                                        - status
                                        - errorMessage
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        id:
                                          type: string
                                          description: Execution id in the project's code.
                                        status:
                                          type: string
                                          description: >-
                                            No answer came from Cargo, so it may
                                            have started. It does not run again.
                                          enum:
                                            - unconfirmed
                                        errorMessage:
                                          type: string
                                          description: What failed while waiting for one.
                                      required:
                                        - id
                                        - status
                                        - errorMessage
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        id:
                                          type: string
                                          description: Execution id in the project's code.
                                        status:
                                          type: string
                                          description: >-
                                            Failed before reaching Cargo. Not
                                            recorded: the next deploy tries again.
                                          enum:
                                            - failed
                                        errorMessage:
                                          type: string
                                          description: What failed.
                                      required:
                                        - id
                                        - status
                                        - errorMessage
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        id:
                                          type: string
                                          description: Execution id in the project's code.
                                        status:
                                          type: string
                                          description: >-
                                            Not started, and still pending: its
                                            approval did not cover it.
                                          enum:
                                            - held
                                        reason:
                                          type: string
                                          description: No approved preview of this spec.
                                          enum:
                                            - notApproved
                                      required:
                                        - id
                                        - status
                                        - reason
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        id:
                                          type: string
                                          description: Execution id in the project's code.
                                        status:
                                          type: string
                                          description: >-
                                            Not started, and still pending: its
                                            approval did not cover it.
                                          enum:
                                            - held
                                        reason:
                                          type: string
                                          description: >-
                                            It matches more records than its
                                            approval allowed.
                                          enum:
                                            - grown
                                        records:
                                          type: number
                                          description: Records it matched.
                                        maxRecords:
                                          type: number
                                          description: Records its approval allowed.
                                      required:
                                        - id
                                        - status
                                        - reason
                                        - records
                                        - maxRecords
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        id:
                                          type: string
                                          description: Execution id in the project's code.
                                        status:
                                          type: string
                                          description: >-
                                            Not started, and still pending: its
                                            approval did not cover it.
                                          enum:
                                            - held
                                        reason:
                                          type: string
                                          description: Its records could not be counted.
                                          enum:
                                            - notCounted
                                        errorMessage:
                                          type: string
                                          description: Why counting failed.
                                      required:
                                        - id
                                        - status
                                        - reason
                                        - errorMessage
                                      additionalProperties: false
                                description: >-
                                  What a deploy did with the executions it found
                                  pending.
                            required:
                              - create
                              - update
                              - noop
                              - delete
                              - resources
                              - impact
                              - executions
                            additionalProperties: false
                          - type: 'null'
                        description: The diff, once it is known.
                      errorMessage:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Why the run failed, if it did.
                      logs:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Command output, truncated.
                      checkRunId:
                        anyOf:
                          - type: number
                          - type: 'null'
                        description: GitHub check run this posted its result to.
                      commentId:
                        anyOf:
                          - type: number
                          - type: 'null'
                        description: GitHub comment this run wrote the plan into.
                      temporalWorkflowId:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Workflow executing this run.
                      startedAt:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Time this run started.
                      finishedAt:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Time this run finished.
                      createdAt:
                        description: Time this run was created.
                        type: string
                      updatedAt:
                        description: Time this run was last updated.
                        type: string
                    required:
                      - uuid
                      - workspaceUuid
                      - stateUuid
                      - kind
                      - trigger
                      - status
                      - headSha
                      - branch
                      - pullRequestNumber
                      - summary
                      - errorMessage
                      - logs
                      - checkRunId
                      - commentId
                      - temporalWorkflowId
                      - startedAt
                      - finishedAt
                      - createdAt
                      - updatedAt
                    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=<remaining>;t=<window seconds>`.
          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 `<limit>;w=<window seconds>`.
          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=<remaining>;t=<window seconds>`.
          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 `<limit>;w=<window seconds>`.
          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=<remaining>;t=<window seconds>`.
          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 `<limit>;w=<window seconds>`.
          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=<remaining>;t=<window seconds>`.
          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 `<limit>;w=<window seconds>`.
          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=<remaining>;t=<window seconds>`.
          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 `<limit>;w=<window seconds>`.
          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=<remaining>;t=<window seconds>`.
          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 `<limit>;w=<window seconds>`.
          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=<remaining>;t=<window seconds>`.
          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 `<limit>;w=<window seconds>`.
          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
        <token>`.
    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.