Mammoth API quickstart
From nothing to a transformed dataset, with the CLI and the Python SDK side by side, and curl for the reads. All of them call the same REST API.
You need an API token first. See Authentication.
1 · Install
CLI
curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | sh
mammoth --version
Python SDK
pip install mammoth-io
curl
# Nothing to install.
2 · Authenticate
export MAMMOTH_API_TOKEN="mm_<your-token>"
CLI
mammoth doctor --output json --no-input # uses MAMMOTH_API_TOKEN from the environment
With MAMMOTH_API_TOKEN set, the CLI uses it and needs no sign-in. On your own machine you can instead run mammoth auth login once and drop the variable; see Authentication.
mammoth-io
The SDK is async: run these steps inside one async def main() and start it with asyncio.run(main()) (in a notebook, await directly).
import asyncio
import os
from mammoth import MammothClient
async def main():
async with MammothClient(
api_token=os.environ["MAMMOTH_API_TOKEN"],
) as client:
... # steps 3 to 7 go here
asyncio.run(main())
3 · Pick a project
Most operations need a project. The workspace comes from the token.
CLI
mammoth project list --output json --no-input
mammoth context project use <PROJECT_ID>
curl
# Ask which workspace the token belongs to: the answer's "id".
curl -sS https://app.mammoth.io/api/v2/workspaces/current \
-H "Authorization: Bearer $MAMMOTH_API_TOKEN"
# {"id": 11, ...}
export MAMMOTH_WORKSPACE_ID=11
curl -sS "https://app.mammoth.io/api/v2/workspaces/$MAMMOTH_WORKSPACE_ID/projects" \
-H "Authorization: Bearer $MAMMOTH_API_TOKEN"
# {"projects": [...], "limit": 10, "offset": 0, "next": "..."}
mammoth-io
await client.projects.list() # {"projects": [...], "offset": 0, ...}
client.set_project_id(PROJECT_ID)
4 · Load some data
CLI
mammoth dataset create --input '{
"dataset_spec": {"url": "https://sampledata.mammoth.io/Multi-Store_Retail_Sales.csv"},
"ds_creation_type": "weburl"
}' --output json --no-input
mammoth-io
await client.datasets.create(
{"url": "https://sampledata.mammoth.io/Multi-Store_Retail_Sales.csv"},
"weburl",
) # returns at once; the dataset may still be loading
await client.datasets.list()
5 · Find the view
A dataset has one or more views, and transformations act on a view, not on the dataset. Take the id of the first one.
CLI
mammoth view list <DATASET_ID> --project <PROJECT_ID> --output json --no-input
curl
curl -sS "https://app.mammoth.io/api/v2/workspaces/$MAMMOTH_WORKSPACE_ID/projects/$PROJECT_ID/datasets/$DATASET_ID/dataviews" \
-H "Authorization: Bearer $MAMMOTH_API_TOKEN"
mammoth-io
await client.dataviews.list(DATASET_ID)
6 · Transform it
A View is the object you work on: it wraps a dataview and carries the transformation methods. Transformations apply in place: each call sends a task to the pipeline, waits for it, and refreshes the view.
CLI
mammoth view transform math <VIEW_ID> --project <PROJECT_ID> \
--input '{"expression": "quantity_sold * unit_price", "new_column": "revenue"}'
mammoth-io
from mammoth import Condition, Operator
view = await client.views.get(VIEW_ID)
await view.filter_rows(Condition("quantity_sold", Operator.GTE, 10))
await view.math("quantity_sold * unit_price", new_column="revenue")
7 · Get the result out
CLI
mammoth view export csv <VIEW_ID> --project <PROJECT_ID> --output json --no-input
The command writes a local file and refuses one that already exists with file_exists (exit 6). Pass --overwrite to replace it.
mammoth-io
await view.export.to_csv("output.csv")
8 · Clean up
Delete anything temporary. Note the confirmation: destructive commands need --yes, and there is no prompt when there is no terminal.
mammoth dataset delete <DATASET_ID> --project <PROJECT_ID> --yes --output json --no-input
Next up
- Command contract: all command families, with blast radius.
- For coding agents: the discovery loop, the envelope, exit codes.