> 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.

# Mammoth API quickstart

> From nothing to a transformed, exported dataset in about five minutes, with the Mammoth CLI and the mammoth-io Python SDK, plus curl for the REST reads.

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](https://mammoth.io/docs/build/auth/).

## 1 · Install


**CLI**

```bash
curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | sh
mammoth --version
```

**Python SDK**

```bash
pip install mammoth-io
```

**curl**

```bash
# Nothing to install.
```


## 2 · Authenticate

```bash
export MAMMOTH_API_TOKEN="mm_<your-token>"
```


**CLI**

```bash
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](https://mammoth.io/docs/build/auth/).

**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).

```python
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())
```


> **One variable, both tools**
>
> The SDK gets the token because you pass it to the client. The CLI reads `MAMMOTH_API_TOKEN` by itself, and while it is set it outranks any saved profile, unless you name one with `--profile` or `MAMMOTH_PROFILE`. The CLI prints one line on stderr when it uses the variable. See [Authentication](https://mammoth.io/docs/build/auth/).

## 3 · Pick a project

Most operations need a project. The workspace comes from the token.


**CLI**

```bash
mammoth project list --output json --no-input
mammoth context project use <PROJECT_ID>
```

**curl**

```bash
# 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**

```python
await client.projects.list()    # {"projects": [...], "offset": 0, ...}
client.set_project_id(PROJECT_ID)
```


## 4 · Load some data


**CLI**

```bash
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**

```python
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()
```


> **Keep the dataset id**
>
> The CLI's response carries it: `{"status": "ready", "dataset_id": 303686, "job_id": 14794754}`. The CLI's create commands block until the dataset is ready, so there is no job to poll by hand.

## 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**

```bash
mammoth view list <DATASET_ID> --project <PROJECT_ID> --output json --no-input
```

**curl**

```bash
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**

```python
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**

```bash
mammoth view transform math <VIEW_ID> --project <PROJECT_ID> \
  --input '{"expression": "quantity_sold * unit_price", "new_column": "revenue"}'
```

**mammoth-io**

```python
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**

```bash
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**

```python
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.

```bash
mammoth dataset delete <DATASET_ID> --project <PROJECT_ID> --yes --output json --no-input
```

## Next up

- [Command contract](https://mammoth.io/docs/build/): all command families, with blast radius.
- [For coding agents](https://mammoth.io/docs/agents/): the discovery loop, the envelope, exit codes.

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