> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/data-connectors/rest-api.md).

# REST API

Connect RootCause to any REST API to import data from external services.

***

### Prerequisites

Before connecting, ensure you have:

* API base URL — or better, a machine-readable spec URL (OpenAPI, Swagger, Google Discovery, OData, or CKAN)
* Authentication credentials (if required)
* Network access from RootCause to the API

***

### Setting Up the Connection

1. Navigate to **Sources** in your workspace and click **Import data**
2. In the Import Manager, find **REST API** and click **Setup**
3. Paste a URL into the **API URL** field and click **Parse**

You can paste an OpenAPI, Swagger, Google Discovery, OData, or CKAN URL — or any working data URL — and RootCause will figure out the base URL, authentication, endpoints, pagination, and where the records live. After parsing, review the detected **Base URL** and endpoint list.

If the API has no spec, click **No spec? Configure manually** and fill in:

| Field               | Description                                           | Example                   |
| ------------------- | ----------------------------------------------------- | ------------------------- |
| Base URL            | Base API endpoint                                     | `https://api.example.com` |
| Authentication Type | None, API Key, Bearer Token, Basic Auth, or OAuth 2.0 | `API Key`                 |

4. Configure authentication (see below)
5. Test an endpoint with real values to verify the connection
6. Click **Save** to create the connector

All requests are sent as `GET` — the connector reads data from your API and never writes to it.

***

### Authentication Methods

**None**

For public APIs that don't require authentication.

**API Key**

For APIs that authenticate via API key:

| Field            | Description              | Example                   |
| ---------------- | ------------------------ | ------------------------- |
| API Key Name     | Header or parameter name | `X-API-Key`, `api_key`    |
| API Key Location | Where to send the key    | Header or Query Parameter |
| API Key          | Your API key value       | `••••••••`                |

**Bearer Token**

For APIs using Bearer token authentication:

| Field        | Description              |
| ------------ | ------------------------ |
| Bearer Token | Your JWT or access token |

**Basic Auth**

For APIs using HTTP Basic Authentication:

| Field    | Description  |
| -------- | ------------ |
| Username | API username |
| Password | API password |

**OAuth 2.0**

For OAuth 2.0 APIs, paste an access token — it is sent as an `Authorization: Bearer` header. Automatic token refresh isn't supported yet, so long-lived tokens work best.

Credentials are encrypted and never leave the backend.

***

### Headers and Query Parameters

You can add default headers and query parameters that will be sent with every request:

**Headers**

Add custom HTTP headers:

```
Accept: application/json
X-Custom-Header: value
```

**Query Parameters**

Add default query string parameters:

```json
{
  "format": "json",
  "limit": "1000"
}
```

Import-specific parameters are merged on top of these defaults.

***

### Importing Data

Once your connector is saved:

1. Click **Import Data** on the connector
2. If a spec was parsed, pick an endpoint from the endpoint list and fill in its **Parameters** — otherwise enter the **Endpoint path** (appended to the base URL)
3. Add import-specific **Query parameters** (merged with defaults)
4. Configure **Pagination** and **Records location** (see below)
5. Click **Test & preview** to fetch a sample page and verify the records before importing

**Pagination**

RootCause follows the API's pagination automatically. When a spec is parsed, the pagination style and parameters are pre-filled. The available styles:

| Style          | How it works                                                             |
| -------------- | ------------------------------------------------------------------------ |
| Single request | One request, no paging (default)                                         |
| Page number    | Increments a page parameter (`page=1`, `page=2`, …)                      |
| Offset / limit | Increments an offset parameter by the page size                          |
| Cursor         | Reads the next cursor from a response field and passes it as a parameter |
| Link header    | Follows the `rel="next"` URL from the `Link` response header             |

Depending on the style, you configure the **Page param**, **Size param**, **Offset param**, or **Cursor param** and **Next cursor path**, plus a **Page size** and an optional **Max pages** cap. Fetching stops when a page comes back empty, when **Max pages** is reached, or at a built-in safety cap of 1,000 pages.

**Records location**

Responses are parsed (JSON, XML, or CSV) and flattened into a table. Use **Records location** to point at the array of records with a dotted path (e.g. `data.items`) — leave it blank to use the whole response. After **Test & preview**, the detected array paths in the actual response are offered as options.

For APIs that return an object of parallel arrays (e.g. `{"time": [...], "temp_max": [...]}`), enable the columnar toggle so the arrays are transposed into rows. RootCause also auto-detects this shape in most cases.

**Column renaming**

An optional response mapping renames columns after the records are flattened:

```json
{
  "userName": "customer_name",
  "createdAt": "signup_date"
}
```

Keys are column names from the flattened response; values are the new column names. This is a plain rename — to pull records out of a nested response, use **Records location** instead.

***

### What Happens When You Import

1. RootCause makes GET requests to the configured endpoint, following pagination
2. Each response is parsed (JSON, XML, or CSV)
3. Records are extracted at the configured records location; columnar responses are transposed into rows
4. Records are flattened into tabular format and any column renames are applied
5. Schema is automatically detected
6. Data is stored in your workspace's data lake

The imported dataset becomes available for use in [Data Views](/user-guide/data-views.md) and [Ontology](/core-technologies/ontology.md) mapping.

***

### Live Data Sync

You can keep the dataset current in two ways:

**Full refresh** (default) — the endpoint is fetched again and the dataset is replaced:

* **Manual** – Only sync when you click "Sync Now"
* **Hourly** – Refresh every hour
* **Daily** – Refresh once per day
* **Weekly** – Refresh once per week
* **Monthly** – Refresh once per month

**Incremental append** — enable **Keep in sync (append new rows)** when configuring the import. Choose how often to sync (**Sync every** Hour, Day, Week, or Month) and, if the endpoint has a date/time parameter, a **Watermark param**. On each sync, RootCause passes the last sync time as the watermark parameter so only new records are fetched, and appends them to the dataset instead of replacing it.

***

### Common Use Cases

**Importing from a CRM**

```
Base URL: https://api.crm.com/v1
Endpoint path: /contacts
Auth: API Key (Header)
Query Params: { "status": "active" }
Pagination: Page number, page size 100
```

**Pulling from an open-data portal**

```
API URL: https://data.gov.uk (CKAN — parsed automatically)
Endpoint: datastore_search
Records location: result.records
```

**Pulling IoT sensor data**

```
Base URL: https://iot.platform.com/api
Endpoint path: /readings
Auth: Basic Auth
Query Params: { "sensor_ids": "1,2,3", "interval": "hourly" }
Sync: Keep in sync (append new rows), watermark on the "since" parameter
```

***

### Troubleshooting

**Connection failed / timeout**

* Verify the URL is correct and accessible
* Check firewall rules and network connectivity
* Ensure the API server is responding

**401 Unauthorized**

* Verify your authentication credentials
* Check that the API key or token hasn't expired
* Ensure you're using the correct authentication method

**Response not recognized**

* Verify the API returns JSON, XML, or CSV (HTML landing pages are rejected)
* Use **Test & preview** to inspect the raw response
* Point **Records location** at the array that holds your records

**Empty data**

* Verify your query parameters return results
* Check that you have access to the requested resources
* Use **Test & preview** to confirm records appear at the selected records location