Cargo API

TypeScript client for the Cargo API. Use it to manage data models, orchestrate workflows, build AI agents, and integrate with the Cargo platform from Node.js or the browser.

API reference: docs.getcargo.ai/api-reference/introduction

Installation

npm install @cargo-ai/api

Peer dependencies

@cargo-ai/api depends on @cargo-ai/types and @cargo-ai/utils, which are published alongside it. Install them if your environment does not already provide them:

npm install @cargo-ai/types @cargo-ai/utils

Usage

Building the API client

Create an API client by calling buildApi with your API token (Bearer auth):

import { buildApi } from "@cargo-ai/api";

const api = buildApi({
  accessToken: "YOUR_API_TOKEN",
});

// Use domain APIs
const datasets = await api.storage.dataset.all();
const workflows = await api.orchestration.workflow.all();

baseUrl defaults to https://api.getcargo.io. Override it if you need to target a different environment:

const api = buildApi({
  baseUrl: "https://custom-api.example.com",
  accessToken: "YOUR_API_TOKEN",
});

Client behavior: HTTP requests use a 6-minute timeout. Long-running operations (e.g. sync, runs) may need to be polled or observed via other means; see the API reference.

Domain clients and types

The package exports typed domain namespaces and API modules for:

• Ai – AI resources, agents, MCP servers, files
• Billing – subscriptions and billing
• Connection – connectors, integrations, filters
• Expression – expressions and formula helpers
• Orchestration – workflows, plays, tools, templates
• RevenueOrganization – members, capacities, territories
• Segmentation – segments, changes
• Storage – datasets, models, relationships, columns
• SystemOfRecordIntegration – systems of record, clients
• UserManagement – users and permissions
• WorkspaceManagement – workspaces, folders, roles, tokens

Each domain exposes sub-areas on the API instance. Examples:

| Domain | Sub-areas (e.g. api.<domain>.<sub>) | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Ai | template, agent, release, chat, message, vote, document, mcpServer, mcpClient, prompt, memory, file, suggestedAction | | Billing | usage, subscription | | Connection | connector, integration, nativeIntegration | | Expression | favoriteRecipe, recipe, expression | | Orchestration | batch, workflow, play, tool, release, draftRelease, run, record, node, template | | RevenueOrganization | allocation, capacity, member, territory | | Segmentation | segment, change, record | | Storage | column, dataset, model, relationship, run, record | | SystemOfRecordIntegration | systemOfRecord, client, log | | UserManagement | user | | WorkspaceManagement | workspace, file, user, token, role, folder |

Use the domain types (from @cargo-ai/api or @cargo-ai/types) for request/response typing and the API instance (api.storage, api.connection, etc.) for HTTP calls.

More usage examples

// Create a connector – a dataset is automatically created for each connector.
const { connector, dataset } = await api.connection.connector.create({
  name: "My HubSpot",
  slug: "my-hubspot",
  integrationSlug: "hubspot",
  config: {
    /* integration-specific credentials / settings */
  },
});

// List storage runs for a model
const runs = await api.storage.run.list({ modelUuid: "...", limit: 20 });

// List orchestration runs with filters
const orchestrationRuns = await api.orchestration.run.list({
  workflowUuid: "...",
  statuses: ["success"],
});

Error handling

import { determineIfIsFetcherError, type FetcherError } from "@cargo-ai/api";

try {
  await api.storage.dataset.get("...");
} catch (err) {
  if (determineIfIsFetcherError(err)) {
    const fetcherError = err as FetcherError;
    console.error(fetcherError.status, fetcherError.body);
  }
}

Requirements

• Node.js 22.x
• TypeScript (for types)

Resources

• Cargo API Reference – Endpoints, authentication, and platform concepts (Datasets, Models, Connectors, Tools, Plays, Agents, etc.)
• API tokens: create in your workspace under Settings → API

License

See the root of the repository for license information.