REST API

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

---

Prerequisites

Before connecting, ensure you have:

• API endpoint URL

• Authentication credentials (if required)

• Understanding of the API response format

• Network access from RootCause.ai to the API

---

Setting Up the Connection

1. Navigate to Data → Datasets in your workspace

2. Click New Connection and select REST API

3. Configure your connection:

Field	Description	Example
Method	HTTP method	GET, POST, PUT, etc.
Default URL	Base API endpoint	https://api.example.com/v1

1. Configure authentication (see below)

2. Add any default headers or query parameters

3. Click Test Connection to verify

4. Click Save to create the connector

---

Authentication Methods

None

For public APIs that don't require authentication.

API Key

For APIs that authenticate via API key:

Field	Description
API Key Name	Header or parameter name
API Key Location	Where to send the key
API Key	Your API key value

Basic Auth

For APIs using HTTP Basic Authentication:

Field	Description
Username	API username
Password	API password

Bearer Token

For APIs using Bearer token authentication:

Field	Description
Bearer Token	Your JWT or access token

OAuth 2.0

For APIs using OAuth 2.0:

Field	Description
Client ID	OAuth client ID
Client Secret	OAuth client secret

---

Headers and Query Parameters

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

Headers

Add custom HTTP headers:

Content-Type: application/json
Accept: application/json
X-Custom-Header: value

Query Parameters

Add default query string parameters:

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

---

Request Body (POST/PUT/PATCH)

For methods that send a request body, you can configure a default JSON body:

{
  "filters": {
    "status": "active"
  },
  "fields": ["id", "name", "created_at"]
}

---

Importing Data

Once your connector is saved:

1. Click Import Data on the connector

2. Optionally override the Path to append to the base URL

3. Add import-specific Query Parameters (merged with defaults)

4. Configure Response Mapping if needed to transform the data

Response Mapping

If your API response has nested data, use response mapping to flatten it:

{
  "id": "response.data.items[].id",
  "name": "response.data.items[].name"
}

---

What Happens When You Import

1. RootCause.ai makes the configured HTTP request

2. JSON response is parsed and flattened into tabular format

3. Arrays are expanded into rows

4. Nested objects are flattened with dot notation

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 configure automatic syncing to keep your dataset current:

• Manual – Only sync when you click "Sync Now"

• Hourly – Refresh every hour

• Daily – Refresh once per day

• Weekly – Refresh once per week

When a sync runs, the API is called again and data is refreshed.

---

Common Use Cases

Importing from a CRM

URL: https://api.crm.com/v1/contacts
Method: GET
Auth: API Key (Header)
Query Params: { "limit": "10000", "status": "active" }

Fetching financial data

URL: https://api.finance.com/transactions
Method: POST
Auth: Bearer Token
Body: { "startDate": "2024-01-01", "endDate": "2024-12-31" }

Pulling IoT sensor data

URL: https://iot.platform.com/api/readings
Method: GET
Auth: Basic Auth
Query Params: { "sensor_ids": "1,2,3", "interval": "hourly" }

---

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

• Check the response structure matches your expectations

• Use response mapping to extract nested data

Empty data

• Verify your query parameters return results

• Check that you have access to the requested resources

• Try the API request manually to verify the response