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

> Get an AI agent by UUID (GET /ai/agents/{uuid}).



## OpenAPI

````yaml https://api.getcargo.io/openapi.json get /ai/agents/{uuid}
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:
  /ai/agents/{uuid}:
    get:
      tags:
        - AI - Agents
      summary: Get agent
      description: Get an AI agent by UUID (GET /ai/agents/{uuid}).
      operationId: getAiAgentsByUuid
      parameters:
        - in: path
          name: uuid
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            title: UUID
            description: Agent identifier.
          required: true
          description: Agent identifier.
      responses:
        '200':
          description: Get agent
          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:
                  agent:
                    type: object
                    properties:
                      uuid:
                        type: string
                        description: Agent identifier.
                      workspaceUuid:
                        type: string
                        description: Workspace this agent belongs to.
                      userUuid:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: User who owns this agent, if any.
                      name:
                        type: string
                        description: Agent display name.
                      icon:
                        type: object
                        properties:
                          color:
                            type: string
                            enum:
                              - grey
                              - green
                              - purple
                              - yellow
                              - blue
                              - red
                            description: Background color of the agent icon.
                          face:
                            type: string
                            description: Face glyph shown on the agent icon.
                        required:
                          - color
                          - face
                        additionalProperties: false
                        description: Icon shown for this agent.
                      description:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: What this agent does, if set.
                      triggers:
                        type: array
                        items:
                          anyOf:
                            - type: object
                              properties:
                                name:
                                  type: string
                                  description: Trigger display name.
                                description:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                  description: What this trigger does, if set.
                                type:
                                  type: string
                                  description: Trigger fires on a cron schedule.
                                  enum:
                                    - cron
                                cron:
                                  type: string
                                  description: Cron expression that fires this trigger.
                                text:
                                  type: string
                                  description: Human-readable form of the cron schedule.
                                temporalScheduleWorkflowId:
                                  type: string
                                  description: >-
                                    Temporal schedule workflow that fires this
                                    trigger.
                              required:
                                - name
                                - description
                                - type
                                - cron
                                - text
                                - temporalScheduleWorkflowId
                              additionalProperties: false
                            - type: object
                              properties:
                                name:
                                  type: string
                                  description: Trigger display name.
                                description:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                  description: What this trigger does, if set.
                                type:
                                  type: string
                                  description: Trigger fires from a connector event.
                                  enum:
                                    - connector
                                connectorUuid:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                  description: Connector that emits this trigger, if bound.
                                integrationSlug:
                                  type: string
                                  description: Integration that defines this trigger.
                                config:
                                  type: object
                                  propertyNames:
                                    type: string
                                  additionalProperties: {}
                                  description: Connector-specific trigger configuration.
                              required:
                                - name
                                - description
                                - type
                                - connectorUuid
                                - integrationSlug
                                - config
                              additionalProperties: false
                            - type: object
                              properties:
                                name:
                                  type: string
                                  description: Trigger display name.
                                description:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                  description: What this trigger does, if set.
                                type:
                                  type: string
                                  description: Trigger fires from a native agent.
                                  enum:
                                    - native
                                agentSlug:
                                  type: string
                                  description: Native agent that fires this trigger.
                                config:
                                  type: object
                                  propertyNames:
                                    type: string
                                  additionalProperties: {}
                                  description: Native agent-specific trigger configuration.
                              required:
                                - name
                                - description
                                - type
                                - agentSlug
                                - config
                              additionalProperties: false
                        description: Triggers that start this agent.
                      deployedRelease:
                        anyOf:
                          - type: object
                            properties:
                              uuid:
                                type: string
                                description: Release identifier.
                              userUuid:
                                type: string
                                description: User who created this release.
                              description:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Release notes, if any.
                              templateSlug:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  Template this release was created from, if
                                  any.
                              version:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Semver of this release, if assigned.
                              actions:
                                type: array
                                items:
                                  allOf:
                                    - type: object
                                      properties:
                                        name:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: Action display name, if set.
                                        slug:
                                          type: string
                                          description: Stable slug that identifies this action.
                                        description:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: What this action does, if set.
                                        isBulkAllowed:
                                          type: boolean
                                          description: >-
                                            Whether this action can run on many
                                            records at once.
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: Action-specific configuration.
                                      required:
                                        - name
                                        - slug
                                        - description
                                        - isBulkAllowed
                                        - config
                                      additionalProperties: false
                                    - anyOf:
                                        - type: object
                                          properties:
                                            kind:
                                              type: string
                                              description: Action invokes a workspace tool.
                                              enum:
                                                - tool
                                            toolUuid:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                              description: Tool this action invokes, if bound.
                                            templateSlug:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                              description: >-
                                                Template this tool was created from, if
                                                any.
                                            waitUntilFinished:
                                              type: boolean
                                              description: >-
                                                Whether the caller waits for the tool to
                                                finish.
                                          required:
                                            - kind
                                            - toolUuid
                                            - templateSlug
                                            - waitUntilFinished
                                          additionalProperties: false
                                        - type: object
                                          properties:
                                            kind:
                                              type: string
                                              description: Action invokes another agent.
                                              enum:
                                                - agent
                                            agentUuid:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                              description: Agent this action invokes, if bound.
                                            templateSlug:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                              description: >-
                                                Template this agent was created from, if
                                                any.
                                            waitUntilFinished:
                                              type: boolean
                                              description: >-
                                                Whether the caller waits for the agent
                                                to finish.
                                          required:
                                            - kind
                                            - agentUuid
                                            - templateSlug
                                            - waitUntilFinished
                                          additionalProperties: false
                                        - type: object
                                          properties:
                                            kind:
                                              type: string
                                              description: Action calls a connector integration.
                                              enum:
                                                - connector
                                            integrationSlug:
                                              type: string
                                              description: Integration that defines this action.
                                            connectorUuid:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                              description: Connector this action calls, if bound.
                                            actionSlug:
                                              type: string
                                              description: Slug of the connector action to run.
                                          required:
                                            - kind
                                            - integrationSlug
                                            - connectorUuid
                                            - actionSlug
                                          additionalProperties: false
                                        - type: object
                                          properties:
                                            kind:
                                              type: string
                                              description: Action is a built-in Cargo action.
                                              enum:
                                                - native
                                            actionSlug:
                                              type: string
                                              description: Slug of the native action to run.
                                          required:
                                            - kind
                                            - actionSlug
                                          additionalProperties: false
                                description: Actions available on this release.
                              capabilities:
                                type: array
                                items:
                                  oneOf:
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: Capability grants a code sandbox.
                                          enum:
                                            - sandbox
                                        config:
                                          type: object
                                          properties:
                                            scope:
                                              description: >-
                                                Surface this sandbox is available on, if
                                                restricted.
                                              type: string
                                              enum:
                                                - chat
                                                - agent
                                          additionalProperties: false
                                          description: Sandbox-specific configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: Capability grants workspace context.
                                          enum:
                                            - context
                                        config:
                                          type: object
                                          properties:
                                            isReadOnly:
                                              description: >-
                                                Whether context may only be read, not
                                                written.
                                              type: boolean
                                          additionalProperties: false
                                          description: Context-specific configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: Capability grants access to a Cargo app.
                                          enum:
                                            - app
                                        config:
                                          type: object
                                          properties:
                                            appUuid:
                                              description: >-
                                                App this capability is scoped to, if
                                                any.
                                              type: string
                                            canPromote:
                                              description: >-
                                                Whether the agent may promote work into
                                                this app.
                                              type: boolean
                                          additionalProperties: false
                                          description: App-specific configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: >-
                                            Capability grants document read and
                                            write.
                                          enum:
                                            - document
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: Document-specific configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: Capability grants web search.
                                          enum:
                                            - webSearch
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: Web-search configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: >-
                                            Capability grants the workspace action
                                            catalog.
                                          enum:
                                            - action
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: Action-catalog configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: Capability grants model read and write.
                                          enum:
                                            - model
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: Model-specific configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: Capability grants file read and write.
                                          enum:
                                            - file
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: File-specific configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: Capability grants documentation search.
                                          enum:
                                            - documentationSearch
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: Documentation-search configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: Capability grants long-term memory.
                                          enum:
                                            - memory
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: Memory-specific configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        slug:
                                          type: string
                                          description: >-
                                            Capability grants suggested next
                                            actions.
                                          enum:
                                            - suggestedActions
                                        config:
                                          type: object
                                          propertyNames:
                                            type: string
                                          additionalProperties: {}
                                          description: Suggested-actions configuration.
                                      required:
                                        - slug
                                        - config
                                      additionalProperties: false
                                  type: object
                                description: Capabilities enabled on this release.
                              suggestedActions:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    text:
                                      type: string
                                      description: Suggested prompt shown to the user.
                                    actions:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          slug:
                                            type: string
                                            description: >-
                                              Action to run when this suggestion is
                                              chosen.
                                        required:
                                          - slug
                                        additionalProperties: false
                                      description: Actions the suggestion will run.
                                  required:
                                    - text
                                    - actions
                                  additionalProperties: false
                                description: Suggested actions shown for this release.
                              systemPrompt:
                                type: string
                                description: System prompt used by this release.
                              withReasoning:
                                type: boolean
                                description: >-
                                  Whether the model is asked to reason before
                                  answering.
                              temperature:
                                type: number
                                description: Sampling temperature for the language model.
                              maxSteps:
                                type: number
                                description: Maximum tool-calling steps the agent may take.
                              integrationSlug:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: LLM integration used by this release, if any.
                              connectorUuid:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Connector for the language model, if any.
                              languageModelSlug:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: Language model used by this release, if any.
                              mcpClients:
                                type: array
                                items:
                                  oneOf:
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          description: MCP client talks to a custom server URL.
                                          enum:
                                            - custom
                                        name:
                                          type: string
                                          description: Display name of this MCP client.
                                        url:
                                          type: string
                                          description: URL of the custom MCP server.
                                        authentication:
                                          anyOf:
                                            - type: object
                                              properties:
                                                issuedAt:
                                                  type: string
                                                  description: Time the access token was issued.
                                                accessToken:
                                                  type: string
                                                  description: OAuth access token.
                                                expiresIn:
                                                  description: >-
                                                    Access-token lifetime in seconds, if
                                                    provided.
                                                  type: number
                                                refreshToken:
                                                  description: OAuth refresh token, if issued.
                                                  type: string
                                                scope:
                                                  description: >-
                                                    OAuth scopes granted to this token, if
                                                    provided.
                                                  type: string
                                                tokenType:
                                                  description: OAuth token type, if provided.
                                                  type: string
                                                clientId:
                                                  description: OAuth client identifier, if stored.
                                                  type: string
                                                clientSecret:
                                                  description: OAuth client secret, if stored.
                                                  type: string
                                              required:
                                                - issuedAt
                                                - accessToken
                                              additionalProperties: false
                                            - type: 'null'
                                          description: >-
                                            OAuth tokens used to call the server, if
                                            any.
                                        disabledToolSlugs:
                                          type: array
                                          items:
                                            type: string
                                          description: >-
                                            MCP tools that are hidden from the
                                            agent.
                                      required:
                                        - kind
                                        - name
                                        - url
                                        - authentication
                                        - disabledToolSlugs
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          description: >-
                                            MCP client is backed by a Cargo
                                            connector.
                                          enum:
                                            - connector
                                        name:
                                          type: string
                                          description: Display name of this MCP client.
                                        connectorUuid:
                                          type: string
                                          description: Connector that hosts this MCP server.
                                        integrationSlug:
                                          type: string
                                          description: >-
                                            Integration that defines this MCP
                                            client.
                                        disabledToolSlugs:
                                          type: array
                                          items:
                                            type: string
                                          description: >-
                                            MCP tools that are hidden from the
                                            agent.
                                      required:
                                        - kind
                                        - name
                                        - connectorUuid
                                        - integrationSlug
                                        - disabledToolSlugs
                                      additionalProperties: false
                                  type: object
                                description: MCP clients attached to this release.
                              resources:
                                type: array
                                items:
                                  anyOf:
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          description: Resource exposes a workspace model.
                                          enum:
                                            - model
                                        name:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: Resource display name, if set.
                                        slug:
                                          type: string
                                          description: >-
                                            Stable slug that identifies this
                                            resource.
                                        description:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: What this resource is for, if set.
                                        prompt:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: >-
                                            Instructions for how the agent should
                                            use this model.
                                        integrationSlug:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: >-
                                            Integration that backs this model, if
                                            any.
                                        modelUuid:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: Model this resource exposes, if bound.
                                        filter:
                                          anyOf:
                                            - type: object
                                              properties:
                                                conjonction:
                                                  type: string
                                                  enum:
                                                    - or
                                                    - and
                                                  description: How groups in this filter are combined.
                                                groups:
                                                  type: array
                                                  items: {}
                                                  description: >-
                                                    Groups of conditions that make up this
                                                    filter.
                                              required:
                                                - conjonction
                                                - groups
                                              additionalProperties: false
                                            - type: 'null'
                                          description: >-
                                            Filter that limits which records the
                                            agent may read.
                                        selectedColumnSlugs:
                                          anyOf:
                                            - type: array
                                              items:
                                                type: string
                                            - type: 'null'
                                          description: >-
                                            Model columns the agent may read, if
                                            restricted.
                                        limit:
                                          anyOf:
                                            - type: number
                                            - type: 'null'
                                          description: >-
                                            Maximum number of records the agent may
                                            read.
                                        isReadOnly:
                                          type: boolean
                                          description: >-
                                            Whether the agent may only read this
                                            model.
                                      required:
                                        - kind
                                        - name
                                        - slug
                                        - description
                                        - prompt
                                        - integrationSlug
                                        - modelUuid
                                        - filter
                                        - selectedColumnSlugs
                                        - limit
                                        - isReadOnly
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          description: Resource exposes files and folders.
                                          enum:
                                            - file
                                        name:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: Resource display name, if set.
                                        slug:
                                          type: string
                                          description: >-
                                            Stable slug that identifies this
                                            resource.
                                        description:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: What this resource is for, if set.
                                        prompt:
                                          anyOf:
                                            - type: string
                                            - type: 'null'
                                          description: >-
                                            Instructions for how the agent should
                                            use these files.
                                        items:
                                          type: array
                                          items:
                                            anyOf:
                                              - type: object
                                                properties:
                                                  kind:
                                                    type: string
                                                    description: Selection is a single file.
                                                    enum:
                                                      - file
                                                  fileUuid:
                                                    type: string
                                                    description: File this selection points to.
                                                required:
                                                  - kind
                                                  - fileUuid
                                                additionalProperties: false
                                              - type: object
                                                properties:
                                                  kind:
                                                    type: string
                                                    description: Selection is a folder of files.
                                                    enum:
                                                      - folder
                                                  folderUuid:
                                                    type: string
                                                    description: Folder this selection points to.
                                                required:
                                                  - kind
                                                  - folderUuid
                                                additionalProperties: false
                                          description: Files and folders this resource exposes.
                                        isReadOnly:
                                          description: >-
                                            When false, the agent may also write new
                                            files into the folders this resource
                                            lists. Unset means read-only.
                                          type: boolean
                                      required:
                                        - kind
                                        - name
                                        - slug
                                        - description
                                        - prompt
                                        - items
                                      additionalProperties: false
                                description: Resources the agent may use.
                              heartbeat:
                                anyOf:
                                  - type: object
                                    properties:
                                      intervalMinutes:
                                        type: integer
                                        exclusiveMinimum: 0
                                        maximum: 9007199254740991
                                        description: Minutes between heartbeat turns.
                                      maxMessages:
                                        type: integer
                                        exclusiveMinimum: 0
                                        maximum: 9007199254740991
                                        description: Maximum heartbeat messages to send.
                                      prompt:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                          - type: 'null'
                                        description: >-
                                          Prompt used for each heartbeat turn, if
                                          set.
                                    required:
                                      - intervalMinutes
                                      - maxMessages
                                      - prompt
                                    additionalProperties: false
                                  - type: 'null'
                                description: Heartbeat configuration, if enabled.
                              evaluator:
                                anyOf:
                                  - type: object
                                    properties:
                                      rubric:
                                        type: string
                                        minLength: 1
                                        description: Rubric used to score the agent.
                                      threshold:
                                        type: number
                                        minimum: 0
                                        maximum: 1
                                        description: >-
                                          Minimum score from 0 to 1 required to
                                          pass.
                                    required:
                                      - rubric
                                      - threshold
                                    additionalProperties: false
                                  - type: 'null'
                                description: Evaluation configuration, if enabled.
                              harnessSlug:
                                anyOf:
                                  - type: string
                                    enum:
                                      - claudeCode
                                      - codex
                                      - openCode
                                      - deepAgents
                                    description: >-
                                      Coding-agent runtime. Null means
                                      streamText.
                                  - type: 'null'
                                description: >-
                                  Coding-agent runtime that drives this release,
                                  if any.
                              repository:
                                anyOf:
                                  - type: object
                                    properties:
                                      connectorUuid:
                                        description: >-
                                          Git connector used to reach the
                                          repository, if any.
                                        type: string
                                      repository:
                                        description: >-
                                          Repository to check out, as an
                                          owner/name full name, if set.
                                        type: string
                                      defaultBranch:
                                        description: Default branch to work on, if set.
                                        type: string
                                      rootDirectory:
                                        description: >-
                                          Directory within the repository to treat
                                          as the project root.
                                        type: string
                                      env:
                                        description: >-
                                          Environment variables available to code
                                          execution.
                                        type: array
                                        items:
                                          oneOf:
                                            - type: object
                                              properties:
                                                key:
                                                  type: string
                                                  minLength: 1
                                                  description: Environment variable name.
                                                type:
                                                  type: string
                                                  description: Value is stored in plaintext.
                                                  enum:
                                                    - public
                                                value:
                                                  type: string
                                                  description: >-
                                                    Plaintext value of the environment
                                                    variable.
                                              required:
                                                - key
                                                - type
                                                - value
                                              additionalProperties: false
                                            - type: object
                                              properties:
                                                key:
                                                  type: string
                                                  minLength: 1
                                                  description: Environment variable name.
                                                type:
                                                  type: string
                                                  description: Value is stored as an encrypted secret.
                                                  enum:
                                                    - secret
                                                secretValue:
                                                  type: object
                                                  properties:
                                                    type:
                                                      type: string
                                                      enum:
                                                        - encryption
                                                    isEncrypted:
                                                      type: boolean
                                                    value:
                                                      type: string
                                                  required:
                                                    - type
                                                    - isEncrypted
                                                    - value
                                                  additionalProperties: false
                                                  description: >-
                                                    Encrypted secret value of the
                                                    environment variable.
                                              required:
                                                - key
                                                - type
                                                - secretValue
                                              additionalProperties: false
                                          type: object
                                      runAsUserUuid:
                                        description: >-
                                          Service user the harness turn runs as.
                                          When set, the sandbox receives a
                                          temporary CARGO_API_TOKEN for that user.
                                        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
                                  - type: 'null'
                                description: >-
                                  Git workspace for a coding harness. Null when
                                  unbound or when harnessSlug is null.
                              deployedAt:
                                anyOf:
                                  - type: string
                                  - type: 'null'
                                description: >-
                                  Time this release was deployed, if it has
                                  been.
                              createdAt:
                                description: Time this release was created.
                                type: string
                            required:
                              - uuid
                              - userUuid
                              - description
                              - templateSlug
                              - version
                              - actions
                              - capabilities
                              - suggestedActions
                              - systemPrompt
                              - withReasoning
                              - temperature
                              - maxSteps
                              - integrationSlug
                              - connectorUuid
                              - languageModelSlug
                              - mcpClients
                              - resources
                              - heartbeat
                              - evaluator
                              - harnessSlug
                              - repository
                              - deployedAt
                              - createdAt
                            additionalProperties: false
                          - type: 'null'
                        description: Currently deployed release, if any.
                      folderUuid:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Folder this agent is filed under, if any.
                      template:
                        anyOf:
                          - type: object
                            properties:
                              slug:
                                type: string
                                description: Template identifier.
                              isAvailable:
                                type: boolean
                                description: Whether this template can be used.
                              scope:
                                type: string
                                enum:
                                  - public
                                  - private
                                description: >-
                                  Whether the template is public or private to
                                  the workspace.
                            required:
                              - slug
                              - isAvailable
                              - scope
                            additionalProperties: false
                          - type: 'null'
                        description: Template this agent was created from, if any.
                      isReadOnly:
                        type: boolean
                        description: Whether this agent cannot be edited.
                      createdAt:
                        description: Time this agent was created.
                        type: string
                      updatedAt:
                        description: Time this agent was last updated.
                        type: string
                      deletedAt:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Time this agent was deleted, if it has been.
                    required:
                      - uuid
                      - workspaceUuid
                      - userUuid
                      - name
                      - icon
                      - description
                      - triggers
                      - deployedRelease
                      - folderUuid
                      - template
                      - isReadOnly
                      - createdAt
                      - updatedAt
                      - deletedAt
                    additionalProperties: false
                    title: Agent
                    description: Agent details.
                required:
                  - agent
                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.