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 for a typed, convenient way to call the API.
Cargo is built around eight core domains that work together to automate your go-to-market operations:
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:
curl -X GET "https://api.getcargo.io/v1/storage/models/list" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Getting your API Token
- Navigate to your workspace settings
- Go to Settings > API Tokens
- Click Create Token and copy the generated token
Keep your API token secure. Never share it publicly or commit it to version
control.
Success Response
Error Response
{
"errorMessage": "Human-readable error message"
}
{
"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. 
