> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Build with Mammoth

> Everything you can do to Mammoth from code, in one place. The CLI, the Python SDK and the REST API, with the endpoint groups, jobs, streams and the contract.

Everything you can do to Mammoth from code. There are three ways in:

- **The CLI** (`mammoth`) is the fastest way to do something once, and the right way to drive Mammoth from an agent or from CI. It describes itself at runtime, so you never have to guess a request shape.
- **The Python SDK** (`mammoth-io`) belongs inside a data pipeline or a notebook. The CLI is built on it and adds no second HTTP client.
- **The REST API** is for everything else.

## Start here

| Page | What it covers |
| --- | --- |
| [Authentication](https://mammoth.io/docs/build/auth/) | Headers, base URL, regions and credential storage |
| [Quickstart](https://mammoth.io/docs/build/quickstart/) | A first real call, three ways |
| [CLI reference](https://mammoth.io/docs/build/cli/) | Every command family, one page each |
| [Python SDK](https://mammoth.io/docs/build/sdk/) | Install `mammoth-io`, create a client, work with views |
| [Errors](https://mammoth.io/docs/build/errors/) | The REST error body, the CLI error envelope, exit codes, rate limits and 429 |
| [Pagination](https://mammoth.io/docs/build/pagination/) | `limit`/`offset` and `next`, a loop that ends, and the few cursor endpoints |
| [Embedding](https://mammoth.io/docs/build/embedding/) | Put a Mammoth board inside a page you control |
| [REST reference](#rest-reference) | The OpenAPI 3.1 document, and how to fetch it with your token |
| [API workflows](https://mammoth.io/docs/guides/advanced/api-workflows/) | Automated workflows over the REST API, in Guides |

## REST reference

Every REST path starts with `https://app.mammoth.io/api/v2`. Send your API token as `Authorization: Bearer mm_...` on every request; see [Authentication](https://mammoth.io/docs/build/auth/).

The OpenAPI 3.1 document is at `https://app.mammoth.io/api/v2/docs/openapi.json`. It is not public: without credentials it answers 401. Fetch it with your API token, or open it in a browser where you are signed in to the web app:

```bash
curl -sS https://app.mammoth.io/api/v2/docs/openapi.json \
  -H "Authorization: Bearer $MAMMOTH_API_TOKEN" -o openapi.json
```

To browse the same reference, open `https://app.mammoth.io/api/v2/docs` in a browser where you are signed in. It shows the document in Swagger UI. The browser page signs you in with the web app's session cookie, so it works only while that session is live.

Every [embedding](https://mammoth.io/docs/build/embedding/) operation, like most of the API, also has a `mammoth dashboard embed` command and a `client.dashboards.embed_*` SDK method.

### Find the workspace your token belongs to

A token belongs to one workspace. Ask the API which one:

```bash
curl -sS https://app.mammoth.io/api/v2/workspaces/current \
  -H "Authorization: Bearer $MAMMOTH_API_TOKEN"
# {"id": 11, "resource": null, "project": null, "projects": null, "read_only": false}
```

`id` is the workspace id to put in every path. `project` and `projects` are set when the token is limited to a project, and `read_only` is true for a read-only connection.

## Endpoint groups

The OpenAPI document lists every operation with its parameters. This table shows where each area lives, so you know what to search for in it. Replace `<workspace_id>` and `<project_id>` with your ids.

| Area | Base path | What you do there |
| --- | --- | --- |
| Workspaces and users | `/workspaces`, `/workspaces/<workspace_id>`, `/workspaces/<workspace_id>/users` | Read the workspace and its members |
| Projects | `/workspaces/<workspace_id>/projects`, `/workspaces/<workspace_id>/projects/<project_id>` | List, create and update projects; `/users` and `/copy` under a project |
| Files and folders | `/workspaces/<workspace_id>/projects/<project_id>/files`, `.../folders` | Upload files to make datasets, manage folders |
| PDF tables | `/workspaces/<workspace_id>/projects/<project_id>/datasets-from-pdf` | Make datasets from the tables in a PDF |
| Datasets | `/workspaces/<workspace_id>/projects/<project_id>/datasets` | Dataset CRUD; `/<dataset_id>/batches` for the batches appended to it |
| Views | `.../datasets/<dataset_id>/dataviews` | View CRUD, `/data` to read rows, `/draft-mode` |
| Pipeline | `.../dataviews/<dataview_id>/pipeline` | `/tasks`, `/exports`, `/checkpoints`, `/data-checks`, `/triggers`, `/versions` |
| Publish to a database | `.../dataviews/<dataview_id>/publish-to-db`, `/workspaces/<workspace_id>/projects/<project_id>/credentials` | Publish a view and read the connection details |
| Automations | `/workspaces/<workspace_id>/projects/<project_id>/automations` | Create, update, run and trash automations; `/<automation_id>/runs` for history |
| Schedules | `/workspaces/<workspace_id>/projects/<project_id>/schedules/<schedule_id>` | Read, update and delete one schedule. Listing a project's schedules is not implemented. |
| Connectors | `/workspaces/<workspace_id>/connectors`, `.../projects/<project_id>/connectors/<connector_key>/connections` | Connect sources and browse their tables |
| Dashboards | `/dashboards` | Boards, publishing, sharing and exports |
| Collections | `/collections` | Collections, members and email updates |
| Parameters and snippets | `/workspaces/<workspace_id>/parameters`, `/workspaces/<workspace_id>/snippets` | Workspace parameters and saved snippets |
| Trash | `/workspaces/<workspace_id>/projects/<project_id>/trash` | List and restore trashed items |
| Resources | `/workspaces/<workspace_id>/resources`, `/workspaces/<workspace_id>/projects/<project_id>/resources` | Search and browse everything in a project |
| Activity log | `/workspaces/<workspace_id>/activity_log` | The workspace audit log |
| Notifications | `/notifications` | Your notifications |
| External API keys | `/workspaces/<workspace_id>/external_keys` | Keys for third-party AI providers |
| API tokens | `/workspaces/<workspace_id>/clientapps` | Create, list, update and delete API tokens |
| Jobs | `/jobs` | Results of asynchronous operations |

An API token cannot manage API tokens. A request to `/workspaces/<workspace_id>/clientapps` made with one is refused with 403 and `"error_code": "4GENR012"`, "Cannot access this API with API-tokens". Create tokens in the web app, or with `mammoth token create` after you sign in with `mammoth auth login`.

## Asynchronous jobs

A slow operation answers **202** with a job instead of a result:

```json
{"job": {"id": 14794754, "status": "processing", "response": {}, "last_updated_at": "2026-11-05T10:00:00", "path": "/api/v2/...", "operation": "..."}}
```

`status` is `processing` until the job ends, then `success`, `failure` or `error`. The result, or the reason it failed, is in `response`. Read a job one of three ways:

| Request | What it returns |
| --- | --- |
| `GET /jobs/<job_id>` | The job, as above. Poll it every few seconds. |
| `GET /jobs?job_ids=10,11,12` | `{"jobs": [...]}`, several jobs in one call |
| `GET /jobs/<job_id>/stream` | Server-sent events: one `job` event with the job when it is done, then the stream ends |

```bash
curl -sS -N "https://app.mammoth.io/api/v2/jobs/$JOB_ID/stream" \
  -H "Authorization: Bearer $MAMMOTH_API_TOKEN"
```

The stream sends a comment line every 15 seconds to keep the connection open, and ends after about two minutes. A stream that ends with no `job` event timed out, not failed: read the job with `GET /jobs/<job_id>`. A job id that does not exist answers 404 with `"error_code": "4JOBS002"`. A job someone else started answers 400 with `4PERM002`.

## Resource change events

`GET /workspaces/<workspace_id>/projects/<project_id>/events/resources/stream` is a server-sent event stream of changes to the resources in one project. Each event's data is a JSON object; `resource_change` events carry `resource_type`, `object_id` and `change_type`. The stream starts with a `connected` comment, sends a `heartbeat` comment every 15 seconds, and ends after about two minutes, so reconnect when it closes. You need access to the project, or the request answers 403.

## Conditional requests with ETags

`GET` on these paths returns a weak `ETag` header, with `Cache-Control: private, must-revalidate` and `Vary: Origin, Authorization`:

- the lists of workspaces, workspace users, projects, folders, datasets and views, and the browse lists
- one workspace, project, folder, dataset or view

Send the value back in `If-None-Match`. When nothing has changed, the API answers **304** with no body, and you keep the copy you have:

```bash
curl -sS -i "https://app.mammoth.io/api/v2/workspaces/$WS/projects/$P/datasets" \
  -H "Authorization: Bearer $MAMMOTH_API_TOKEN" \
  -H 'If-None-Match: W/"<etag>"'
```

A token limited to one project gets no ETag on lists. The Resources endpoints set their own ETag and honour `If-None-Match` the same way.

## Request size limits

A file upload (`POST .../files`) is refused above 50 MiB with **413**. Other request bodies are refused above 10,000,000 bytes, except a few that take large files, such as a BI workbook import.

## The v1 API is legacy

Older integrations call paths under `/api/v1` with a key and secret. That API is not documented here and gets no new endpoints. Build every new integration on `/api/v2` with an API token. To move an old one over, see [Authentication](https://mammoth.io/docs/build/auth/).

## Command contract

The full command table is on the [capability contract](https://mammoth.io/docs/build/contract.md) page, and as JSON at https://mammoth.io/docs/build/capabilities.json.

Every capability in one searchable, filterable table: the CLI command, the Python SDK method, the REST endpoint where one is resolved, and the blast radius (how much damage the operation can do), so you can see what an operation costs before you run it. The table is generated from the CLI's own description of itself: `mammoth schema list` for every command, and `mammoth capability list` for the SDK method and API operation behind it. Nothing on it is hand-authored.

See the [CLI reference](https://mammoth.io/docs/build/cli/) for the command families one at a time, or fetch it as data: [the raw contract](https://mammoth.io/docs/build/contract/) in Markdown, or `https://mammoth.io/docs/build/capabilities.json` as JSON, which is smaller to parse.

---
Source: https://mammoth.io/docs/build.md · Updated: 2026-11-02
