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

4. Configure authentication (see below)
5. Add any default headers or query parameters
6. Click **Test Connection** to verify
7. 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:

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

***

### Request Body (POST/PUT/PATCH)

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

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

```json
{
  "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](https://docs.rootcause.ai/user-guide/data-management/data-views) and [Ontology](https://docs.rootcause.ai/core-technologies/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