> ## 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 every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually. > The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles. > Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up. > Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate. # List actions > List connector, native, tool, and agent actions. Unauthenticated requests return the public connector and native catalog; tools, agents, custom integrations, and workspace connectors require a signed-in workspace. Each result includes an action payload for execute, execute-batch, or get-output-schema. (GET /orchestration/actions/list). ## OpenAPI ````yaml https://api.getcargo.io/openapi.json get /orchestration/actions/list openapi: 3.1.0 info: title: Cargo API version: 1.0.0 description: >- Cargo Platform API v1. ## Authentication Every endpoint requires a bearer token: `Authorization: Bearer `. There is no unauthenticated endpoint. Create a token with `cargo-ai login`, or complete OAuth 2.0 authorization code with PKCE (the `oauth2` scheme). Authorization-server metadata (RFC 8414) is at `https://getcargo.eu.auth0.com/.well-known/oauth-authorization-server`. ## Errors Every 4xx and 5xx response uses the shared `Error` schema: a JSON object carrying `errorMessage`, a human-readable description of what went wrong. A long tail of orchestration routes carries `reason` instead, a machine-readable cause. Routes may add fields (`retryAfter` on a 429), so treat the object as open rather than closed. ## Rate limits Requests are counted per workspace. Every `/v1` response, including the 401 an unauthenticated caller gets, carries `RateLimit` (`"workspace";r=;t=`), `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`, and the legacy `X-RateLimit-*` spellings alongside them. A 429 carries `Retry-After` in seconds: back off by that, rather than retrying immediately. ## Idempotency POST, PUT and PATCH accept an optional `Idempotency-Key` header. A retry with the same key and the same request returns the original response instead of creating a second record. Reusing a key with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Multipart file uploads do not accept the header: the body is not parsed until after the key would have to be fingerprinted. ## Versioning and deprecation The version is in the path (`/v1`), and a breaking change ships as a new path rather than by altering this one. Adding a field to a response, a new optional request field, or a new endpoint is not breaking, so a client must ignore fields it does not recognise. The deprecation policy is at https://docs.getcargo.ai/api-reference/versioning. When an endpoint is being retired it carries the `Deprecation` header (RFC 9745) and, once a removal date is fixed, `Sunset` (RFC 8594). Both are HTTP dates. There are at least 180 days between them. An endpoint marked `deprecated` in this document is still served until its `Sunset` passes. No `/v1` operation is currently deprecated. ## Long-running operations Creating a run or a batch does not wait for the work to finish. The create request returns `202 Accepted` with a `Location` header pointing at the run or batch. Poll that URL (or `GET` the run / batch by `uuid`) until it reaches a terminal status (`success`, `error`, `cancelled`, or `skipped`). Do not retry the create request while the job is still running. Action execute endpoints follow the same pattern unless `waitUntilFinished` is true, in which case a finished job is `200`. servers: - url: https://api.getcargo.io/v1 description: Cargo API security: - bearerAuth: [] - oauth2: - openid - profile - email - offline_access externalDocs: description: API versioning and deprecation policy url: https://docs.getcargo.ai/api-reference/versioning paths: /orchestration/actions/list: get: tags: - Orchestration - Actions summary: List actions description: >- List connector, native, tool, and agent actions. Unauthenticated requests return the public connector and native catalog; tools, agents, custom integrations, and workspace connectors require a signed-in workspace. Each result includes an action payload for execute, execute-batch, or get-output-schema. (GET /orchestration/actions/list). operationId: getOrchestrationActionsList parameters: - in: query name: query schema: title: Query description: >- Keywords matched against action slug, name, description, and integration. All terms must match. type: string description: >- Keywords matched against action slug, name, description, and integration. All terms must match. - in: query name: kind schema: title: Kind description: >- Restrict results to one action kind. tool and agent require a signed-in workspace. type: string enum: - connector - native - tool - agent description: >- Restrict results to one action kind. tool and agent require a signed-in workspace. - in: query name: integrationSlug schema: title: Integration slug description: Restrict connector actions to this integration. type: string description: Restrict connector actions to this integration. - in: query name: limit schema: title: Limit description: Maximum results to return (default 20, max 50). type: integer exclusiveMinimum: 0 maximum: 50 description: Maximum results to return (default 20, max 50). responses: '200': description: List actions headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: type: object properties: query: type: string title: Query description: Normalized search terms. totalMatches: type: number title: Total matches description: Number of matches before applying the limit. results: type: array items: type: object properties: name: type: string title: Name description: Action display name. description: title: Description description: Truncated action description. type: string score: type: number title: Score description: Relevance score. Higher is a better match. action: allOf: - type: object properties: retry: description: Retry policy for this action, if any. type: object properties: maximumAttempts: description: >- Maximum number of attempts before giving up. type: number initialInterval: description: >- Initial delay in milliseconds before the first retry. type: number backoffCoefficient: description: >- Multiplier applied to the delay after each retry. type: number additionalProperties: false additionalProperties: false - anyOf: - 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 - type: object properties: kind: type: string description: Action calls a connector integration. enum: - connector connectorUuid: description: Connector to call, if bound. type: string integrationSlug: type: string description: Integration that defines this action. actionSlug: type: string description: Slug of the connector action to run. required: - kind - integrationSlug - actionSlug additionalProperties: false - type: object properties: kind: type: string description: Action invokes a workspace tool. enum: - tool toolUuid: description: Tool to invoke, if bound. type: string templateSlug: description: >- Template this tool was created from, if any. type: string releaseUuid: description: Specific tool release to run, if pinned. type: string waitUntilFinished: description: >- Whether the parent waits for the tool to finish. type: boolean required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - agent description: Action invokes an agent. agentUuid: description: Agent to invoke, if bound. type: string templateSlug: description: >- Template this agent was created from, if any. type: string releaseUuid: description: >- Specific agent release to run, if pinned. type: string waitUntilFinished: description: >- Whether the parent waits for the agent to finish. type: boolean required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - worker description: Action calls a hosted worker. workerUuid: type: string description: Worker that handles this request. method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method used to call the worker. path: type: string description: Path on the worker to call. headers: description: HTTP headers sent to the worker, if any. type: object propertyNames: type: string additionalProperties: type: string required: - kind - workerUuid - method - path additionalProperties: false title: Action description: >- Payload to pass to execute, execute-batch, or get-output-schema. connectors: title: Connectors description: Workspace connectors for this integration. type: array items: type: object properties: uuid: type: string slug: type: string name: type: string required: - uuid - slug - name additionalProperties: false credits: title: Credits description: Credit costs, when the action is billed. type: array items: {} autocompletes: title: Autocompletes description: >- Input fields that need a picked value from the connector. type: array items: type: object properties: slug: type: string title: Slug description: Autocomplete slug. params: title: Params description: >- JSON schema of params this autocomplete requires, if any. required: - slug additionalProperties: false required: - name - score - action additionalProperties: false title: Found action description: A matching action and the payload to execute it. title: Results description: Matching actions, highest score first. required: - query - totalMatches - results 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=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: >- Too many requests. Retry after the number of seconds in the Retry-After header. headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal server error headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;t=`. schema: type: string example: '"workspace";r=999;t=60' RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer example: 1000 RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer example: 999 RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer example: 60 RateLimit-Policy: description: Declared policy as `;w=`. schema: type: string example: 1000;w=60 X-RateLimit-Limit: description: Legacy spelling of RateLimit-Limit. schema: type: integer example: 1000 X-RateLimit-Remaining: description: Legacy spelling of RateLimit-Remaining. schema: type: integer example: 999 X-RateLimit-Reset: description: Legacy spelling of RateLimit-Reset. schema: type: integer example: 60 Deprecation: description: >- RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Sat, 01 Aug 2026 00:00:00 GMT Sunset: description: >- RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served. At least 180 days after Deprecation. See https://docs.getcargo.ai/api-reference/versioning. schema: type: string example: Thu, 28 Jan 2027 00:00:00 GMT content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object properties: errorMessage: description: Human-readable description of what went wrong. type: string reason: description: >- Machine-readable cause, used where a route distinguishes failure modes. type: string additionalProperties: {} description: Error response securitySchemes: bearerAuth: type: http scheme: bearer description: >- API token from `cargo-ai login`. Send as `Authorization: Bearer `. oauth2: type: oauth2 description: >- OAuth 2.0 authorization code with PKCE (S256). Discover endpoints from https://getcargo.eu.auth0.com/.well-known/oauth-authorization-server. Include `audience=https://api.getcargo.io` in the authorization request to obtain a JWT valid for this API. flows: authorizationCode: authorizationUrl: https://getcargo.eu.auth0.com/authorize tokenUrl: https://getcargo.eu.auth0.com/oauth/token scopes: openid: OpenID Connect identity. profile: Name and profile claims. email: Email address. offline_access: Refresh token. ````