Skip to content
Documentation: open the docs menu

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

PageWhat it covers
AuthenticationHeaders, base URL, regions and credential storage
QuickstartA first real call, three ways
CLI referenceEvery command family, one page each
Python SDKInstall mammoth-io, create a client, work with views
ErrorsThe REST error body, the CLI error envelope, exit codes, rate limits and 429
Paginationlimit/offset and next, a loop that ends, and the few cursor endpoints
EmbeddingPut a Mammoth board inside a page you control
REST referenceThe OpenAPI 3.1 document, and how to fetch it with your token
API workflowsAutomated 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.

AreaBase pathWhat you do there
Workspaces and users/workspaces, /workspaces/<workspace_id>, /workspaces/<workspace_id>/usersRead 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, .../foldersUpload files to make datasets, manage folders
PDF tables/workspaces/<workspace_id>/projects/<project_id>/datasets-from-pdfMake datasets from the tables in a PDF
Datasets/workspaces/<workspace_id>/projects/<project_id>/datasetsDataset CRUD; /<dataset_id>/batches for the batches appended to it
Views.../datasets/<dataset_id>/dataviewsView 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>/credentialsPublish a view and read the connection details
Automations/workspaces/<workspace_id>/projects/<project_id>/automationsCreate, 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>/connectionsConnect sources and browse their tables
Dashboards/dashboardsBoards, publishing, sharing and exports
Collections/collectionsCollections, members and email updates
Parameters and snippets/workspaces/<workspace_id>/parameters, /workspaces/<workspace_id>/snippetsWorkspace parameters and saved snippets
Trash/workspaces/<workspace_id>/projects/<project_id>/trashList and restore trashed items
Resources/workspaces/<workspace_id>/resources, /workspaces/<workspace_id>/projects/<project_id>/resourcesSearch and browse everything in a project
Activity log/workspaces/<workspace_id>/activity_logThe workspace audit log
Notifications/notificationsYour notifications
External API keys/workspaces/<workspace_id>/external_keysKeys for third-party AI providers
API tokens/workspaces/<workspace_id>/clientappsCreate, list, update and delete API tokens
Jobs/jobsResults 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:

RequestWhat 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>/streamServer-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

FamilyCommandsExamples
activity2activity export, activity list
addon6addon connector add, addon connector remove, addon storage add
agent45agent access askers, agent access chart save, agent access grant give
ai5ai condition generate, ai expression generate, ai retention condition
annotation5annotation comment add, annotation create, annotation delete
auth5auth connected-apps list, auth connected-apps revoke, auth login
automation13automation capabilities, automation create, automation delete
batch7batch bulk-delete, batch create, batch create-spec
billing27billing chargebee-plan, billing hosted-page, billing invoice charge
browse9browse ancestors, browse folder, browse project
capability3capability find, capability get, capability list
client-app5client-app create, client-app delete, client-app get
collection21collection active-job, collection activity, collection create
completion2completion install, completion show
config4config get, config list, config path
connector42connector active, connector ai chat, connector ai history
context4context project clear, context project status, context project use
dashboard167dashboard action, dashboard analytics, dashboard archive
dataset37dataset batch-data, dataset broken-rows list, dataset broken-rows resolve
external-key4external-key create, external-key delete, external-key get
file11file bulk-delete, file delete, file extract-sheets
folder10folder bulk-delete, folder create, folder delete
history4history list, history resume, history show
job4job get, job get-many, job wait
log2log path, log tail
notification5notification delete, notification delete-batch, notification list
other61calc, capabilities, doctor
parameter14parameter create, parameter delete, parameter dependencies
project25project bulk-delete, project bulk-update, project check
recipe2recipe list, recipe run
schedule5schedule create, schedule delete, schedule get
schema3schema find, schema get, schema list
skill7skill agents-md install, skill install, skill list
snippet8snippet create, snippet delete, snippet dependencies
support117support billing cancel-subscription, support billing change-plan, support billing end-trial
template5template create, template delete, template get
token3token create, token list, token revoke
trash3trash add, trash list, trash restore
user7user avatar delete, user avatar upload, user delete-account
view146view active-user list, view active-user mark, view ai generate-data
webhook7webhook create, webhook delete, webhook get
workflow31workflow archive, workflow attach-dataset, workflow block add
workspace33workspace accept-invite, workspace app-usage, workspace check-expression

Report an issue · support@mammoth.io