Skip to content
Build with Mammoth: open the docs menu

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

Report an issue · support@mammoth.io