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

1. Configure authentication (see below)

2. Test an endpoint with real values to verify the connection

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

{
  "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:

{
  "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 and Ontology 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