# Cargo API

TypeScript client for the [Cargo API](https://docs.getcargo.ai/api-reference/introduction). 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](https://docs.getcargo.ai/api-reference/introduction)

## Installation

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

```bash
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):

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

```ts
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
- **Content** – knowledge files and libraries
- **Context** – context repository, runtime sandbox, knowledge graph
- **Expression** – expressions and formula helpers
- **Hosting** – Cargo Hosting apps, workers, deployments, env vars, custom domains
- **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                                                                            |
| **Content**                   | file, library                                                                                                        |
| **Context**                   | repository, runtime, graph                                                                                           |
| **Expression**                | favoriteRecipe, recipe, expression                                                                                   |
| **Hosting**                   | app, worker, deployment, envVars, customDomain                                                                       |
| **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

```ts
// 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

```ts
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](https://docs.getcargo.ai/api-reference/introduction)** – 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.