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

# API Reference

> Complete reference for the Cargo REST API

The Cargo API allows you to programmatically interact with the Cargo platform. Use it to manage your data models, orchestrate workflows, build AI agents, and integrate with your existing systems.

For JavaScript and TypeScript, you can use our official client library [@cargo-ai/api](https://www.npmjs.com/package/@cargo-ai/api) for a typed, convenient way to call the API.

## Platform Overview

Cargo is built around eight core domains that work together to automate your go-to-market operations:

```mermaid theme={null}
flowchart LR
    subgraph Storage["Storage"]
        Dataset["Dataset"]
        Model["Model"]
        Dataset --> Model
    end

    subgraph Segmentation["Segmentation"]
        Segment["Segment"]
        Change["Change"]
        Segment --> Change
    end

    subgraph Connections["Connection"]
        Connector["Connector"]
        Action["Action"]
        Extractor["Extractor"]
        Connector --> Action
        Connector --> Extractor
    end

    subgraph Content["Content"]
        File["File"]
        Library["Library"]
    end

    subgraph Context["Context"]
        Repository["Repository"]
        Graph["Knowledge Graph"]
        Repository --> Graph
    end

    subgraph Orchestration["Orchestration"]
        Tool["Tool"]
        Play["Play"]
        Workflow["Workflow"]
        Tool --> Workflow
        Play --> Workflow
    end

    subgraph AI["AI"]
        Agent["Agent"]
    end

    subgraph Hosting["Hosting"]
        Deployment["Deployment"]
        App["App"]
        Worker["Worker"]
        Deployment --> App
        Deployment --> Worker
    end

    Extractor -->|"syncs to"| Model
    Connector -->|"backs"| Library
    Model -->|"filters into"| Segment
    Change -->|"triggers"| Play
    Action -->|"sequenced in"| Workflow
    Action -->|"available in"| Agent
    Play -->|"orchestrates"| Tool
    Agent -->|"uses"| Tool
    Agent -->|"searches"| Model
    Agent -->|"searches"| File
    Agent -->|"searches"| Library
    Agent -->|"references"| Graph
```

### Core Entities

| Entity              | Description                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Dataset**         | A collection of Models. Organizes your data into logical groups.                                                   |
| **Model**           | Structured tables (Companies, Contacts, etc.) that store your data.                                                |
| **Connector**       | An authenticated connection to an external service (HubSpot, Salesforce, etc.).                                    |
| **Extractor**       | Syncs data from a Connector into a Model.                                                                          |
| **Action**          | Operations provided by Connectors (enrich, write to CRM, send email, etc.). Available in Tools, Plays, and Agents. |
| **Segment**         | A filtered subset of a Model's records.                                                                            |
| **Change**          | Records entering or exiting a Segment. Used to trigger Plays.                                                      |
| **Tool**            | Reusable automation units. Can be triggered manually, via API, or used by Agents and Plays.                        |
| **Workflow**        | The step-by-step automation logic within a Tool or Play. Defines the sequence of Actions to execute.               |
| **Play**            | Event-driven automations that trigger on Changes. Orchestrate Tools and Actions.                                   |
| **Agent**           | AI-powered workers that use reasoning to execute tasks. Can call Tools, use Actions, and search Models.            |
| **File**            | Documents uploaded for Agents to search and reference.                                                             |
| **Library**         | A native or connector-backed collection of documents, indexed for Agent retrieval (RAG).                           |
| **Repository**      | A git-backed store of markdown/MDX GTM context for the workspace.                                                  |
| **Knowledge Graph** | The relationship graph built from the Context repository, giving Agents structured GTM context.                    |
| **App**             | A hosted Vite SPA served on `*.cargo.app` that reads workspace data via the Cargo API.                             |
| **Worker**          | A serverless edge HTTP handler that runs custom logic against the Cargo API.                                       |
| **Deployment**      | A shipped and promoted version of a hosted App or Worker.                                                          |

## Base URL

All API requests should be made to:

```
https://api.getcargo.io/v1
```

## Authentication

The Cargo API uses Bearer token authentication. Include your API token in the `Authorization` header of all requests:

```bash theme={null}
curl -X GET "https://api.getcargo.io/v1/storage/models/list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Getting your API Token

1. Navigate to your workspace settings
2. Go to **Settings** > **API Tokens**
3. Click **Create Token** and copy the generated token

<Warning>
  Keep your API token secure. Never share it publicly or commit it to version
  control.
</Warning>

## Response Format

All API responses are returned in JSON format. Data is returned directly at the root level.

### Success Response

```json theme={null}
{
  "models": [...]
}
```

### Error Response

```json theme={null}
{
  "errorMessage": "Human-readable error message"
}
```

Or for specific error types:

```json theme={null}
{
  "reason": "modelNotFound"
}
```

## Rate Limiting

API requests are rate-limited per workspace. If you exceed the rate limit, you'll receive a `429 Too Many Requests` response.