Build with Mammoth
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 | Headers, base URL, regions and credential storage |
| Quickstart | A first real call, three ways |
| CLI reference | Every command family, one page each |
| Python SDK | Install mammoth-io, create a client, work with views |
| Errors | The REST error body, the CLI error envelope, exit codes, rate limits and 429 |
| Pagination | limit/offset and next, a loop that ends, and the few cursor endpoints |
| Embedding | Put a Mammoth board inside a page you control |
| REST reference | The OpenAPI 3.1 document, and how to fetch it with your token |
| 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.
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:
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 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:
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:
{"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 |
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:
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.
Command contract
926 commands across 43 families, CLI 2.4.2 (2026-11-02). Full JSON
| Family | Commands | Examples |
|---|---|---|
| activity | 2 | activity export, activity list |
| addon | 6 | addon connector add, addon connector remove, addon storage add |
| agent | 45 | agent access askers, agent access chart save, agent access grant give |
| ai | 5 | ai condition generate, ai expression generate, ai retention condition |
| annotation | 5 | annotation comment add, annotation create, annotation delete |
| auth | 5 | auth connected-apps list, auth connected-apps revoke, auth login |
| automation | 13 | automation capabilities, automation create, automation delete |
| batch | 7 | batch bulk-delete, batch create, batch create-spec |
| billing | 27 | billing chargebee-plan, billing hosted-page, billing invoice charge |
| browse | 9 | browse ancestors, browse folder, browse project |
| capability | 3 | capability find, capability get, capability list |
| client-app | 5 | client-app create, client-app delete, client-app get |
| collection | 21 | collection active-job, collection activity, collection create |
| completion | 2 | completion install, completion show |
| config | 4 | config get, config list, config path |
| connector | 42 | connector active, connector ai chat, connector ai history |
| context | 4 | context project clear, context project status, context project use |
| dashboard | 167 | dashboard action, dashboard analytics, dashboard archive |
| dataset | 37 | dataset batch-data, dataset broken-rows list, dataset broken-rows resolve |
| external-key | 4 | external-key create, external-key delete, external-key get |
| file | 11 | file bulk-delete, file delete, file extract-sheets |
| folder | 10 | folder bulk-delete, folder create, folder delete |
| history | 4 | history list, history resume, history show |
| job | 4 | job get, job get-many, job wait |
| log | 2 | log path, log tail |
| notification | 5 | notification delete, notification delete-batch, notification list |
| other | 61 | calc, capabilities, doctor |
| parameter | 14 | parameter create, parameter delete, parameter dependencies |
| project | 25 | project bulk-delete, project bulk-update, project check |
| recipe | 2 | recipe list, recipe run |
| schedule | 5 | schedule create, schedule delete, schedule get |
| schema | 3 | schema find, schema get, schema list |
| skill | 7 | skill agents-md install, skill install, skill list |
| snippet | 8 | snippet create, snippet delete, snippet dependencies |
| support | 117 | support billing cancel-subscription, support billing change-plan, support billing end-trial |
| template | 5 | template create, template delete, template get |
| token | 3 | token create, token list, token revoke |
| trash | 3 | trash add, trash list, trash restore |
| user | 7 | user avatar delete, user avatar upload, user delete-account |
| view | 146 | view active-user list, view active-user mark, view ai generate-data |
| webhook | 7 | webhook create, webhook delete, webhook get |
| workflow | 31 | workflow archive, workflow attach-dataset, workflow block add |
| workspace | 33 | workspace accept-invite, workspace app-usage, workspace check-expression |