Skip to main content
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.

​
Platform Overview

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

​
Core Entities

EntityDescription
DatasetA collection of Models. Organizes your data into logical groups.
ModelStructured tables (Companies, Contacts, etc.) that store your data.
ConnectorAn authenticated connection to an external service (HubSpot, Salesforce, etc.).
ExtractorSyncs data from a Connector into a Model.
ActionOperations provided by Connectors (enrich, write to CRM, send email, etc.). Available in Tools, Plays, and Agents.
SegmentA filtered subset of a Model’s records.
ChangeRecords entering or exiting a Segment. Used to trigger Plays.
ToolReusable automation units. Can be triggered manually, via API, or used by Agents and Plays.
WorkflowThe step-by-step automation logic within a Tool or Play. Defines the sequence of Actions to execute.
PlayEvent-driven automations that trigger on Changes. Orchestrate Tools and Actions.
AgentAI-powered workers that use reasoning to execute tasks. Can call Tools, use Actions, and search Models.
FileDocuments uploaded for Agents to search and reference.

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