> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://docs.mammoth.io/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# REST API

> Connect Mammoth to any HTTP or HTTPS JSON endpoint with the REST API connector: authenticate, set a data root path, paginate, test, and save a dataset.

The REST API connector imports data from any HTTP/HTTPS JSON endpoint into Mammoth as a dataset. Unlike other connectors that authenticate to a specific service, this connector lets you connect to any REST API endpoint—internal services, SaaS APIs, custom backends, or public data sources.

Setting up a REST API connection defaults to an **AI-assisted chat**: describe the API in plain language and Mammoth's assistant asks for the URL, credentials, and other details it needs, testing the connection as it goes. A **Classic form** is also available if you'd rather fill in every field yourself—click **Classic form** at any point during the chat to switch.

## Before you start

You need:

- The **base URL** of the API you want to connect to (e.g., `https://api.example.com`)
- **Authentication credentials** if the API requires them (API key, Bearer token, Basic auth credentials, or an OAuth 2.0 app's client ID and secret)
- Knowledge of the API endpoint path and expected response structure

## Step 1: Select the REST API connector

1. In Mammoth, go to **Data Library** and click **+ New Dataset**
2. Select **Connectors**
3. Search for **REST API**
4. Click the **REST API** tile

![New Dataset dialog with Connectors selected, REST API typed in search, and the REST API tile shown](https://docs.mammoth.io/api/v1/images/20260826_100621_RestAPI-Card.png)

## Step 2: Set up the connection with the AI assistant (default)

By default, Mammoth opens a chat panel—**Mammoth Analytics AI Assistance**—instead of a static form.

![REST API AI assistant chat with a message box, example chips (Jira, GitHub, NASA API), and a Classic form link](https://docs.mammoth.io/api/v1/images/20260826_100913_RestAPI-Connectionscreen.png)

1. Type what you want to connect to and why—for example, *"Connect to the NASA API and pull the astronomy picture of the day"*—or click one of the example chips (**Jira**, **GitHub**, **NASA API**, **Custom REST API**) to start from a template
2. The assistant asks follow-up questions as needed (base URL, endpoint, auth type) and may show an inline **credential form** in the chat when it needs a key, token, or username/password—fill it in and click **Submit** without leaving the conversation
3. For OAuth-based APIs, the assistant shows an **Authorize Access** button that sends you to the provider's login in the same browser tab; once you approve access, you return to Mammoth and the chat resumes
4. The assistant tests the connection and endpoint for you—messages such as "Connection test passed" or "Connection test failed" and "Endpoint test passed" or "Endpoint test failed" appear inline, along with a **Sample data** preview when the test succeeds
5. If you already have a saved REST API connection, the assistant may show a **connection picker** so you can reuse it, or click **Connect new account** to create a new one
6. Once the assistant confirms the setup, it may ask you to choose which columns to keep (**Select columns to import**). Click **Apply**, or **Skip / Keep all** to keep every column
7. Click **Done** once the dataset is created

> **Tip: Switch to the classic form anytime.**
> Click **Classic form** in the chat panel to switch to the traditional field-based setup described below instead—useful if you already know the exact configuration and want to skip the conversation.

## Step 3: Or configure the connection manually (classic form)

Click **Classic form** to open the field-based connection setup instead of the AI chat. The **REST API - New Connection** dialog opens.

![REST API New Connection form with Base URL, Display Name, six authentication type tabs including OAuth 2.0 Client Credentials, and Advanced Settings](https://docs.mammoth.io/api/v1/images/20261009_182028_Connector-RestAPI-ClassicForm.jpg)

### Basic settings

| Field | Description | Example |
| --- | --- | --- |
| **Base URL** | The root URL for all requests—endpoint paths are appended to this | `https://api.example.com/v2` |
| **Display Name** | A label for this connection (defaults to the Base URL if left blank) | `Example API` |

### Authentication

Select the authentication type used by your API:

| Auth Type | When to use | Fields required |
| --- | --- | --- |
| **No Authentication** | Public APIs with no authentication |—|
| **API Key** | APIs that accept a key in a header or query parameter | Key Name and Key Value (Param Name and Param Value for a query parameter); choose **Header** or **Query Parameter** |
| **Bearer Token** | APIs that use `Authorization: Bearer <token>` | Bearer Token |
| **Basic Auth** | APIs that use HTTP Basic authentication | Username and Password |
| **OAuth 2.0 Authorization Code** | APIs that require a full OAuth 2.0 login flow | Client ID, Client Secret, Authorization URL, Token URL, and optional Scopes |
| **OAuth 2.0 Client Credentials** | Server-to-server APIs that issue a client ID and secret | Client ID, Client Secret, Token URL, and optional Scopes |

### API Key placement

- **Header**—sends the key as a request header (for example, `X-API-Key: your-key-here`)
- **Query Parameter**—appends the key to the URL (for example, `?api_key=your-key-here`)

**OAuth 2.0 Authorization Code** adds three extra fields under **Advanced Settings**: **Redirect URI** (defaults to `https://redirect.mammoth.io/redirect/oauth2` if left blank), a **Client Auth Method** selector (**Client Secret POST** or **Client Secret Basic**), and a **Use PKCE (Proof Key for Code Exchange)** toggle for providers that require or support PKCE. Clicking **Connect** with this auth type sends you to the provider's login page in the same browser tab rather than saving immediately. **OAuth 2.0 Client Credentials** has no browser sign-in: Mammoth requests the access token from the Token URL.

### Advanced settings (optional)

Expand **Advanced Settings** to configure:

| Setting | Description | Default |
| --- | --- | --- |
| **Timeout (sec)** | How long Mammoth waits for a response before timing out | 30 |
| **Rate Limit (req/s)** | Maximum requests per second to send (helps avoid API rate limits) | Unlimited |
| **Verify SSL Certificate** | Verify the server's SSL certificate | Enabled |

Click **Connect** to save the connection (or to start the OAuth redirect, for OAuth 2.0 Authorization Code). If saving fails, the error message appears at the bottom of the dialog.

## Step 4: Configure the REST API endpoint

After saving the connection, select it under **Existing Connections**. The **Endpoint Configuration** screen opens, where you configure the specific endpoint to import data from.

### Endpoint settings

| Field | Description | Example |
| --- | --- | --- |
| **Endpoint Path** | The path appended to your base URL | `/users` or `/reports/daily` |
| **HTTP Method** | The request method | GET (default) or POST |
| **Request Body** | JSON body for POST requests | `{"start": "2024-01-01"}` |

Mammoth shows the full URL (base URL plus endpoint path) in a callout as you type the endpoint path.

### Data root path

The **Data Root Path** tells Mammoth where to find the array of records within the JSON response. Most APIs return data nested inside a wrapper object.

| Response structure | Data Root Path |
| --- | --- |
| Top-level array: `[{...}, {...}]` | `$` (default) |
| Nested: `{"data": [{...}, {...}]}` | `$.data` |
| Deeply nested: `{"result": {"items": [...]}}` | `$.result.items` |

After testing the endpoint, Mammoth suggests available root paths based on the actual response structure—click a suggestion to apply it automatically.

### Flatten nested JSON

The **Flatten Nested JSON** toggle (enabled by default) converts nested objects into flat columns using dot notation. For example, a field `{"address": {"city": "NYC"}}` becomes a column named `address.city`.

## Step 5: Configure REST API pagination (optional)

If the API returns data across multiple pages, configure pagination so Mammoth fetches all records.

![REST API pagination options (No Pagination, Offset, Cursor, Page #, Link) above Save as Dataset with a Test button](https://docs.mammoth.io/api/v1/images/20260826_101221_RestAPI-Paginationoptions.png)

Select a pagination type:

| Type | Use when | Required settings |
| --- | --- | --- |
| **No Pagination** | API returns all data in one response | — |
| **Offset** | API uses `limit` and `offset` query parameters | Page Size (default 100) |
| **Cursor** | API returns a cursor token for the next page | Cursor Path (where to find the next cursor in the response) |
| **Page #** | API uses a `page` query parameter | Page Size (default 100) |
| **Link** | API returns pagination links in the `Link` HTTP header (RFC 5988) |—|

### Advanced pagination settings

Click **Advanced options** to expand:

- **Limit Param** and **Offset Param**—customize if the API uses non-standard names (for example, `count` instead of `limit`)
- **Cursor Param**—customize the query parameter name for the cursor value
- **Page Param**—customize the query parameter name for the page number
- **Max Pages**—set a limit to stop fetching after N pages (useful for large datasets during testing). Leave it empty to fetch all pages

## Step 6: Test and save the REST API dataset

Click **Test** to run a sample request. Mammoth shows:

- The HTTP status code (for example, `200 OK`)
- A success or error message
- **Suggested data paths:** based on the response—click one to use it as the Data Root Path

In the **Save as Dataset** section, enter a name in **Save table as**, choose an **Update Method** (**Replace all data** or **Add new data**), and click **Save as dataset**. The dataset appears in the **Data Library**.

## REST API configuration examples

### Public API with no auth

```plaintext
Base URL:        https://api.open-meteo.com
Endpoint Path:   /v1/forecast?latitude=40.71&longitude=-74.01&hourly=temperature_2m
Data Root Path:  $.hourly
Pagination:      No Pagination
```

### SaaS API with a Bearer token and cursor pagination

```plaintext
Base URL:        https://api.example.com/v2
Auth:            Bearer — your-token-here
Endpoint Path:   /events
Data Root Path:  $.data
Pagination:      Cursor — cursor path: $.next_cursor
```

### Internal API with an API key header and offset pagination

```plaintext
Base URL:        https://internal.mycompany.com/api
Auth:            API Key → Header → X-API-Key: secret-key
Endpoint Path:   /records
Data Root Path:  $.results
Pagination:      Offset — page size: 500
```

## Troubleshoot REST API connections

### Test returns 401 or 403

- Check the authentication type and credentials are correct
- For API Key auth, confirm whether the key should go in a **Header** or **Query Parameter**—check your API documentation

### The request times out

- The API may be slow to respond—increase the **Timeout (sec)** value in Advanced Settings
- Check that the Base URL is reachable from the internet (some internal APIs require VPN or IP whitelisting)

### Data root path not found

- Use the suggested paths shown after a successful test
- Check the raw JSON response structure in your API documentation or test the endpoint in a tool like Postman first

### Only partial data imported

- If the API uses non-standard parameter names (for example, `count` instead of `limit`), click **Advanced options** under Pagination and update the parameter names to match
- Set **Max Pages** to a small number (for example, 5) to verify pagination is working before importing the full dataset

### SSL certificate error

- Disable **Verify SSL Certificate** in Advanced Settings if you're connecting to an internal API with a self-signed certificate

---
Source: https://docs.mammoth.io/learn/connectors/rest-api.md · Updated: 2026-10-13