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 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:

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

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

Keep your API token secure. Never share it publicly or commit it to version control.

Response Format

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

Success Response

{
  "models": [...]
}

Error Response

{
  "errorMessage": "Human-readable error message"
}

Or for specific error types:

{
  "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.