Cargo

https://docs.getcargo.ai
Admin
Cargo is an AI-powered platform that helps revenue teams automate go-to-market workflows through...
Tokens:2,072,990
Snippets:7,073
Trust Score:7.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Behavior prompt example

Source: https://docs.getcargo.ai/agents/prompt

An example outlining the step-by-step workflow and output format for the agent.

```text
1. Use the "Company-Lookup" action to retrieve company data from the URL
2. Check the company against our ICP criteria in the Knowledge Base
3. Assign a qualification score: "High Fit", "Medium Fit", or "No Fit"
4. Provide a 2-3 sentence explanation of your reasoning
```

--------------------------------

### Example resource description

Source: https://docs.getcargo.ai/agents/resources-and-context

A sample description used to guide the agent on how to interpret or prioritize specific folder content.

```text
This folder contains our sales playbooks. Prioritize the
objection handling guide when the user asks about pricing concerns.
```

--------------------------------

### Install and Login via CLI

Source: https://docs.getcargo.ai/api-reference/authentication

Install the Cargo CLI and authenticate using an email address to create an account and workspace.

```sh
npm install -g @cargo-ai/cli
cargo-ai login --email you@company.com
```

--------------------------------

### Clone and install dummy integration repository

Source: https://docs.getcargo.ai/integration/custom-integration

Clones the dummy-integration repository and installs dependencies. Run these commands in your terminal to set up the integration server locally.

```bash
git clone https://github.com/getcargohq/dummy-integration.git
cd dummy-integration
npm install
```

--------------------------------

### Role/Purpose prompt example

Source: https://docs.getcargo.ai/agents/prompt

A concise example defining the agent's identity and primary objective.

```text
You are a lead qualification specialist for Cargo. Your job is to evaluate
LinkedIn company URLs and determine if they match our Ideal Customer Profile.
```

--------------------------------

### Example Cargo Tool URL path

Source: https://docs.getcargo.ai/tools/embed-in-crm

Example path to replace `CARGOPATH` in the OpenAPI schema. Use only the path portion starting with `/v1` and ending with `execute`.

```text
/v1/tools/e276dc32-aca1-4136-bbe7-dce879346c58/execute
```

--------------------------------

### Install and authenticate the Cargo AI CLI

Source: https://docs.getcargo.ai/cli/overview

Installs the CLI globally via npm and authenticates using an API token. If a global installation is not desired, prefix commands with npx @cargo-ai/cli.

```bash
npm install -g @cargo-ai/cli && cargo-ai login --token <your-api-token>
```

--------------------------------

### Example Project Tree

Source: https://docs.getcargo.ai/get-started/project-layout

Shows a typical project layout with connectors, folders, models, tools, agents, plays, MCP servers, context, files, workers, and apps.

```text
my-workspace/
├── package.json          # scripts: "plan": "cargo-ai cdk plan", "deploy": "cargo-ai cdk deploy"
├── tsconfig.json         # includes .cargo-ai/**/*.d.ts for typed config
├── cargo.state.json      # written by `cdk init` — commit it
├── connectors/
│   ├── hubspot.ts        # defineConnector + secret()
│   └── openai.ts         # defineConnector({ adopt: true })
├── folders/crm.ts        # defineFolder (per-kind: model, agent, …)
├── models/contacts.ts    # defineModel — dataset handle + extractSlug + schedule
├── tools/enrich.ts       # defineWorkflow + defineTool
├── agents/
│   ├── enricher.ts       # defineAgent (sub-agent)
│   └── sdr.ts            # defineAgent (models, tools, subAgents, triggers, evaluator)
├── plays/onboarding.ts   # definePlay + per-row defineWorkflow
├── mcp/crm.ts            # defineMcpServer
├── context/              # defineContext + markdown/MDX
├── files/                # defineFile + local content
├── workers/webhook/      # defineWorker → a built bundle
└── apps/dashboard/       # defineApp → a Vite bundle
```

--------------------------------

### GET /storage/relationships/list

Source: https://docs.getcargo.ai/api-reference/storage--relationships/list-relationships

Lists all relationships in the workspace using the GET /storage/relationships/list endpoint.

```APIDOC
## GET /storage/relationships/list

### Description
List all relationships in the workspace.

### Method
GET

### Endpoint
/storage/relationships/list

### Parameters
None documented.

### Response
#### Success Response (200)
No response schema documented.

#### Response Example
No response example documented.

### Authentication
Requires a bearer token: `Authorization: Bearer <token>`.

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

--------------------------------

### GET /mailboxManagement/suppressions

Source: https://docs.getcargo.ai/api-reference/mailbox-management--suppressions/list-suppressions

Documentation for the GET /mailboxManagement/suppressions endpoint, which lists suppressed addresses for the workspace.

```APIDOC
## GET /mailboxManagement/suppressions

### Description
List the addresses the workspace may no longer send to.

### Method
GET

### Endpoint
/mailboxManagement/suppressions

### Parameters
#### Query Parameters
- None documented.

### Request Example
No request body or query parameters are documented.

### Response
#### Success Response (200)
- No response schema is documented.

#### Response Example
No response example is documented.

### Authentication
Requires a bearer token: `Authorization: Bearer <token>`.

### Errors
Uses the shared `Error` schema with `errorMessage` field.

### Rate Limits
Requests are counted per workspace; rate limit headers are returned on every response.

### Idempotency
Not applicable for GET requests.

### Versioning
Endpoint is under `/v1` path prefix; no deprecation currently.
```

--------------------------------

### Plan and deploy infrastructure

Source: https://docs.getcargo.ai/get-started/quickstart

Use the CLI to plan infrastructure changes and deploy resources, ensuring the state is recorded in cargo.state.json.

```bash
cargo-ai cdk plan               # diff against this project's deploy state
cargo-ai cdk deploy             # create everything; record it in the state
```

--------------------------------

### Create service account and key with gcloud CLI

Source: https://docs.getcargo.ai/reference/system-of-record/bigquery

CLI steps to create a service account, grant BigQuery and Storage permissions, and create a JSON key file. Replace your-project-id with your actual project ID.

```bash
gcloud iam service-accounts create cargo-bigquery \
    --display-name="Cargo BigQuery Service Account"
```

```bash
gcloud projects add-iam-policy-binding your-project-id \
    --member="serviceAccount:cargo-bigquery@your-project-id.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataEditor"

gcloud projects add-iam-policy-binding your-project-id \
    --member="serviceAccount:cargo-bigquery@your-project-id.iam.gserviceaccount.com" \
    --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding your-project-id \
    --member="serviceAccount:cargo-bigquery@your-project-id.iam.gserviceaccount.com" \
    --role="roles/storage.objectUser"
```

```bash
gcloud iam service-accounts keys create cargo-bigquery-key.json \
    --iam-account=cargo-bigquery@your-project-id.iam.gserviceaccount.com
```

--------------------------------

### Plan infrastructure changes

Source: https://docs.getcargo.ai/deploy/deploying

Compiles resources and compares them against the current deploy state without making changes. Output indicates actions as + create, ~ update, = noop, or - delete.

```bash
cargo-ai cdk plan
```

--------------------------------

### npm Install Command for @cargo-ai/form-sdk

Source: https://docs.getcargo.ai/tools/public-form

Install the Cargo form SDK for SPA or framework projects.

```bash
npm install @cargo-ai/form-sdk
```

--------------------------------

### Context directory structure

Source: https://docs.getcargo.ai/context/overview

Example of a directory structure where files under the defined path are synced on deploy.

```text
context/
├── context.ts
├── icp.md
└── personas/
    └── head-of-growth.md
```

--------------------------------

### GET /orchestration/tools/list

Source: https://docs.getcargo.ai/api-reference/orchestration--tools/list-tools

Documentation for the GET /orchestration/tools/list endpoint, which lists all tools in the orchestration tools collection.

```APIDOC
## [GET] /orchestration/tools/list

### Description
Lists all tools available in the orchestration tools collection.

### Method
GET

### Endpoint
https://api.getcargo.io/v1/orchestration/tools/list

### Authentication
- **bearerAuth** (header) - Required - Bearer token: `Authorization: Bearer <token>`
- **oauth2** (OAuth 2.0 authorization code with PKCE) - Required - Scopes: `openid`, `profile`, `email`, `offline_access`

### Parameters
None documented.

### Request Example
No request body or parameters are documented.

### Response
#### Success Response (200)
- **tools** (array) - List of available tools.

#### Response Example
No response example is provided in the source.

### Error Handling
- **4xx/5xx** - Returns the shared `Error` schema with `errorMessage` (string) and optionally `reason` (string).
- **429** - Rate limit exceeded; includes `retryAfter` (integer) and `Retry-After` header.

### Rate Limits
Requests are counted per workspace. Response headers include `RateLimit`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`, and legacy `X-RateLimit-*` headers.

### Idempotency
Not applicable for GET requests.

### Versioning
Endpoint is under `/v1`; breaking changes are introduced via new paths. No deprecation headers are currently present.
```

--------------------------------

### Create object model and columns via CLI

Source: https://docs.getcargo.ai/models/object-models

Use the storage commands to list datasets, create a custom model, and add columns to it.

```bash
cargo-ai storage dataset list                     # → the native datasetUuid

# Create a custom object model
cargo-ai storage model create \
  --slug sourced_leads --name "Sourced Leads" \
  --dataset-uuid <datasetUuid> --extractor-slug csv --config '{}'

# Add columns
cargo-ai storage column create --model-uuid <model-uuid> \
  --column '{"slug":"email","type":"string","label":"Email","kind":"custom"}'
cargo-ai storage column create --model-uuid <model-uuid> \
  --column '{"slug":"website","type":"string","label":"Website","kind":"custom"}'
```

--------------------------------

### GET /orchestration/releases/draft

Source: https://docs.getcargo.ai/api-reference/orchestration--releases/get-draft-release

Retrieves the draft release for a specified workflow using the GET /orchestration/releases/draft endpoint.

```APIDOC
## GET /orchestration/releases/draft

### Description
Get the draft release for a given workflow.

### Method
GET

### Endpoint
/orchestration/releases/draft

### Parameters
#### Query Parameters
- **workflowUuid** (string, uuid) - Required - Workflow whose draft release should be returned.

### Response
#### Success Response (200)
- **release** (object) - The draft release object.
  - **uuid** (string) - Release identifier.
  - **parentUuid** (string or null) - Release this one was created from, if any.
  - **workspaceUuid** (string) - Workspace this release belongs to.
  - **userUuid** (string) - User who created this release.
  - **workflowUuid** (string) - Workflow this release belongs to.
  - **description** (string or null) - Release notes, if any.
  - **version** (string or null) - Semver of this release, if assigned.
  - **status** (string) - Whether this release is draft, deployed, or archived. Enum: draft, deployed, archived.
  - **templateSlug** (string or null) - Template slug.

#### Response Example
{
  "release": {
    "uuid": "string",
    "parentUuid": "string",
    "workspaceUuid": "string",
    "userUuid": "string",
    "workflowUuid": "string",
    "description": "string",
    "version": "string",
    "status": "draft",
    "templateSlug": "string"
  }
}
```

--------------------------------

### Deploy infrastructure

Source: https://docs.getcargo.ai/deploy/deploying

Applies changes in dependency order and persists state. Includes options for interactive prompts, non-TTY environments, and dry runs.

```bash
cargo-ai cdk deploy            # create/update; prompts before applying
cargo-ai cdk deploy --yes      # skip the prompt (required in CI / non-TTY)
cargo-ai cdk deploy --dry-run  # show the plan, change nothing
```

--------------------------------

### Manage and add cookbooks

Source: https://docs.getcargo.ai/cli/manifest

List available cookbooks, view details of a specific cookbook, and add it to an existing repository.

```bash
cargo-ai cdk cookbook list          # what is available
cargo-ai cdk cookbook view cookbook/tam-building
cargo-ai cdk add cookbook/tam-building
```

--------------------------------

### Avoidances prompt example

Source: https://docs.getcargo.ai/agents/prompt

An example establishing negative constraints to ensure compliance and prevent undesired actions.

```text
- Never share proprietary ICP criteria with external parties
- Do not make up information if a lookup fails—report the failure instead
- Avoid overly casual language; maintain a professional tone
```

--------------------------------

### List and run orchestration tools

Source: https://docs.getcargo.ai/get-started/quickstart

List available orchestration workflows and execute a run with specific input data.

```bash
cargo-ai orchestration tool list                         # → workflowUuid
cargo-ai orchestration run create \
  --workflow-uuid <uuid> \
  --data '{"email":"ada@acme.com"}' \
  --wait-until-finished
```

--------------------------------

### GET /orchestration/runs/{uuid}

Source: https://docs.getcargo.ai/api-reference/orchestration--runs/get-run

Get an orchestration run by UUID. This is the status resource returned as Location from POST /orchestration/runs.

```APIDOC
## GET /orchestration/runs/{uuid}

### Description
Get an orchestration run by UUID. This is the status resource returned as Location from POST /orchestration/runs.

### Method
GET

### Endpoint
/orchestration/runs/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string, uuid) - Required - Run identifier.

### Response
#### Success Response (200)
- **run** (object) - The orchestration run object.
  - **uuid** (string) - Run identifier.
  - **workspaceUuid** (string) - Workspace this run belongs to.
  - **workflowUuid** (string) - Workflow this run executed.
  - **userUuid** (string or null) - User who started this run, if any.
  - **releaseUuid** (string or null) - Release this run executed, if any.
  - **nodes** (array or null) - List of nodes in the run.
    - **uuid** (string, uuid) - Node identifier.
    - **slug** (string) - Node slug.

#### Response Headers
- **RateLimit** (string) - Current quota under the workspace policy, as `"workspace";r=<remaining>;t=<window seconds>`.
- **RateLimit-Limit** (integer) - Maximum requests allowed in the current window.
- **RateLimit-Remaining** (integer) - Requests remaining in the current window.
- **RateLimit-Reset** (integer) - Seconds until the current window resets.
- **RateLimit-Policy** (string) - Declared policy as `<limit>;w=<window seconds>`.
- **X-RateLimit-Limit** (integer) - Legacy spelling of RateLimit-Limit.
- **X-RateLimit-Remaining** (integer) - Legacy spelling of RateLimit-Remaining.
- **X-RateLimit-Reset** (integer) - Legacy spelling of RateLimit-Reset.
- **Deprecation** (string) - RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began.
- **Sunset** (string) - RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served.

#### Response Example
{
  "run": {
    "uuid": "string",
    "workspaceUuid": "string",
    "workflowUuid": "string",
    "userUuid": "string or null",
    "releaseUuid": "string or null",
    "nodes": [
      {
        "uuid": "string",
        "slug": "string"
      }
    ]
  }
}
```

--------------------------------

### GET /orchestration/batches/{uuid}

Source: https://docs.getcargo.ai/api-reference/orchestration--batches/get-batch

Get an orchestration batch by UUID. This is the status resource returned as Location from POST /orchestration/batches.

```APIDOC
## GET /orchestration/batches/{uuid}

### Description
Get an orchestration batch by UUID. This is the status resource returned as Location from POST /orchestration/batches.

### Method
GET

### Endpoint
/orchestration/batches/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string, uuid) - Required - Batch identifier.

### Response
#### Success Response (200)
- **batch** (object) - Batch details.
  - **uuid** (string) - Batch identifier.
  - **workspaceUuid** (string) - Workspace this batch belongs to.
  - **workflowUuid** (string) - Workflow this batch executed.
  - **userUuid** (string or null) - User who started this batch, if any.
  - **releaseUuid** (string or null) - Release this batch executed, if any.
  - **nodes** (array or null) - Node details.
    - **uuid** (string, uuid) - Node identifier.
    - **slug** (string) - Node slug.

#### Response Example
{
  "batch": {
    "uuid": "string",
    "workspaceUuid": "string",
    "workflowUuid": "string",
    "userUuid": "string or null",
    "releaseUuid": "string or null",
    "nodes": [
      {
        "uuid": "string",
        "slug": "string"
      }
    ]
  }
}

### Headers
- **RateLimit** (string) - Current quota under the workspace policy, as `"workspace";r=<remaining>;t=<window seconds>`.
- **RateLimit-Limit** (integer) - Maximum requests allowed in the current window.
- **RateLimit-Remaining** (integer) - Requests remaining in the current window.
- **RateLimit-Reset** (integer) - Seconds until the current window resets.
- **RateLimit-Policy** (string) - Declared policy as `<limit>;w=<window seconds>`.
- **X-RateLimit-Limit** (integer) - Legacy spelling of RateLimit-Limit.
- **X-RateLimit-Remaining** (integer) - Legacy spelling of RateLimit-Remaining.
- **X-RateLimit-Reset** (integer) - Legacy spelling of RateLimit-Reset.
- **Deprecation** (string) - RFC 9745. Present only when this operation is deprecated. HTTP-date of when deprecation began.
- **Sunset** (string) - RFC 8594. Present once a removal date is fixed. HTTP-date of when the operation will stop being served.
```
Tokens:
Raw