> ## 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.

# Link GitHub installation

> Complete an install or authorize URL: once the state was signed for this workspace and the caller, link every installation of the Cargo GitHub app on an account the OAuth code's GitHub user administers (an organization owner, or the user itself). (POST /workspaceManagement/githubInstallations).



## OpenAPI

````yaml https://api.getcargo.io/openapi.json post /workspaceManagement/githubInstallations
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/githubInstallations:
    post:
      tags:
        - Workspace Management - GitHub Installations
      summary: Link GitHub installation
      description: >-
        Complete an install or authorize URL: once the state was signed for this
        workspace and the caller, link every installation of the Cargo GitHub
        app on an account the OAuth code's GitHub user administers (an
        organization owner, or the user itself). (POST
        /workspaceManagement/githubInstallations).
      operationId: postWorkspaceManagementGithubInstallations
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  type: string
                  minLength: 1
                  maxLength: 2048
                  title: State
                  description: >-
                    The `state` GitHub handed back, from the install or
                    authorize URL.
                code:
                  type: string
                  minLength: 1
                  maxLength: 512
                  title: Code
                  description: >-
                    The OAuth `code` GitHub handed back with the installation's
                    user authorization.
              required:
                - state
                - code
              additionalProperties: false
              title: Request body
              description: Request body schema.
      responses:
        '200':
          description: Link GitHub installation
          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:
                  githubInstallations:
                    type: array
                    items:
                      type: object
                      properties:
                        uuid:
                          type: string
                          description: Link identifier.
                        workspaceUuid:
                          type: string
                          description: Workspace the installation is linked to.
                        installationId:
                          type: number
                          description: The Cargo GitHub app installation's GitHub id.
                        accountLogin:
                          type: string
                          description: GitHub user or organization the app is installed on.
                        accountType:
                          type: string
                          enum:
                            - User
                            - Organization
                          description: >-
                            Whether the installation is on a user or an
                            organization.
                        linkedByUserUuid:
                          type: string
                          description: Member who linked it.
                        createdAt:
                          description: Time it was first linked.
                          type: string
                        updatedAt:
                          description: Time it was last linked.
                          type: string
                      required:
                        - uuid
                        - workspaceUuid
                        - installationId
                        - accountLogin
                        - accountType
                        - linkedByUserUuid
                        - createdAt
                        - updatedAt
                      additionalProperties: false
                    title: GitHub installations
                    description: >-
                      What was linked: every installation of the Cargo GitHub
                      app on an account the caller administers.
                required:
                  - githubInstallations
                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.