> ## 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. # Connect domain > Connect a domain the workspace already owns elsewhere; free, and pending until its ownership record is published (POST /domainManagement/domains/connect). ## OpenAPI ````yaml https://api.getcargo.io/openapi.json post /domainManagement/domains/connect 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: /domainManagement/domains/connect: post: tags: - Domain Management - Domains summary: Connect domain description: >- Connect a domain the workspace already owns elsewhere; free, and pending until its ownership record is published (POST /domainManagement/domains/connect). operationId: postDomainManagementDomainsConnect parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object properties: name: title: Name description: >- Domain the workspace already owns, registered elsewhere (e.g. acme-outreach.com). type: string minLength: 4 maxLength: 253 required: - name additionalProperties: false title: Request body description: Request body schema. responses: '200': description: Connect domain 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: domain: type: object properties: uuid: 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)$ description: Domain identifier. workspaceUuid: 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)$ description: Workspace this domain belongs to. name: type: string description: Apex domain name. status: type: string enum: - pending - active - failed - cancelled - expired description: Current lifecycle status of this domain. registrar: type: string enum: - mailpool - external description: >- Registrar this domain was purchased through, or `external` when the workspace registered it elsewhere. meta: type: object propertyNames: type: string additionalProperties: {} description: Registrar metadata stored on this domain. dnsRecords: type: array items: type: object properties: type: type: string enum: - A - AAAA - CNAME - MX - TXT - NS - SRV - CAA description: DNS record type. name: type: string description: DNS record hostname. value: type: string description: DNS record value. ttl: anyOf: - type: number - type: 'null' description: Time-to-live for this record in seconds, if set. priority: anyOf: - type: number - type: 'null' description: >- MX or SRV priority, if this record type uses one. required: - type - name - value - ttl - priority additionalProperties: false description: DNS records that must be configured for this domain. verification: type: array items: type: object properties: type: type: string enum: - A - AAAA - CNAME - MX - TXT - NS - SRV - CAA description: DNS record type. name: type: string description: DNS record hostname. value: type: string description: DNS record value. ttl: anyOf: - type: number - type: 'null' description: Time-to-live for this record in seconds, if set. priority: anyOf: - type: number - type: 'null' description: >- MX or SRV priority, if this record type uses one. required: - type - name - value - ttl - priority additionalProperties: false description: >- Records to publish at your own DNS provider to prove ownership. Only external domains have any. verifiedAt: anyOf: - type: string - type: 'null' description: >- Time this domain was first observed active, if it has been. priceCredits: anyOf: - type: number - type: 'null' description: Credit cost of this domain, if priced. billingUsageUuid: anyOf: - 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)$ - type: 'null' description: >- Billing usage record for the purchase or last renewal, if any. expiresAt: anyOf: - type: string - type: 'null' description: Time this domain registration expires, if known. renewalChargedUntil: anyOf: - type: string - type: 'null' description: >- End of the last period credits were charged for, if any. autoRenew: type: boolean description: >- Whether this domain should renew automatically when it expires. userUuid: 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)$ description: User who purchased this domain. createdAt: description: Time this domain was created. type: string updatedAt: description: Time this domain was last updated. type: string deletedAt: anyOf: - type: string - type: 'null' description: Time this domain was deleted, if it has been. required: - uuid - workspaceUuid - name - status - registrar - meta - dnsRecords - verification - verifiedAt - priceCredits - billingUsageUuid - expiresAt - renewalChargedUntil - autoRenew - userUuid - createdAt - updatedAt - deletedAt additionalProperties: false title: Domain description: >- Newly connected domain. It starts `pending` and carries the DNS records to publish; it becomes `active` once Cargo finds them. required: - domain additionalProperties: false '400': $ref: '#/components/responses/BadRequest' content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' content: application/json: schema: $ref: '#/components/schemas/Error' '404': $ref: '#/components/responses/NotFound' content: application/json: schema: $ref: '#/components/schemas/Error' '409': $ref: '#/components/responses/Conflict' content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/UnprocessableEntity' content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/TooManyRequests' content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: IdempotencyKey: in: header name: Idempotency-Key schema: description: >- Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was. example: 8e03978e-40d5-43e8-bc93-6894a57f9324 type: string maxLength: 255 description: >- Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was. responses: BadRequest: description: Bad request headers: RateLimit: description: >- Current quota under the workspace policy, as `"workspace";r=;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' Conflict: description: A request with this Idempotency-Key is already in progress. 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' UnprocessableEntity: description: Idempotency-Key was reused with a different 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' 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. ````