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

# Get install URL

> Links, for the caller and valid for 30 minutes: one that installs the Cargo GitHub app, and one that authorizes it for accounts it is already installed on. Either returns to Cargo and links every installation of the app the caller administers to this workspace (GET /workspaceManagement/githubInstallations/installUrl).



## OpenAPI

````yaml https://api.getcargo.io/openapi.json get /workspaceManagement/githubInstallations/installUrl
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/installUrl:
    get:
      tags:
        - Workspace Management - GitHub Installations
      summary: Get install URL
      description: >-
        Links, for the caller and valid for 30 minutes: one that installs the
        Cargo GitHub app, and one that authorizes it for accounts it is already
        installed on. Either returns to Cargo and links every installation of
        the app the caller administers to this workspace (GET
        /workspaceManagement/githubInstallations/installUrl).
      operationId: getWorkspaceManagementGithubInstallationsInstallUrl
      responses:
        '200':
          description: Get install URL
          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:
                  installUrl:
                    type: string
                    title: Install URL
                    description: >-
                      Installs the Cargo GitHub app, then links every
                      installation of it the caller administers to this
                      workspace. Valid for 30 minutes, for the caller only.
                  authorizeUrl:
                    type: string
                    title: Authorize URL
                    description: >-
                      Authorizes the Cargo GitHub app and links every
                      installation of it the caller administers, for accounts it
                      is already installed on. Valid for 30 minutes, for the
                      caller only.
                required:
                  - installUrl
                  - authorizeUrl
                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'
        '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:
  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'
    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.