> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Sources API

> Create, update, list, and delete data source configurations for ingesting external data.

Data sources define external data feeds that bring data into the platform. Each data source is associated with a connector type and sync configuration, and can be linked to a target schema for automatic data loading.

<Info>
  See the [Data Platform feature page](/data/overview) for details on connectors, schemas, and the data ingestion pipeline.
</Info>

## Base path

```
/api/v1/data-sources
```

***

## List data sources

```
GET /api/v1/data-sources
```

Returns a paginated list of data sources for the current tenant, ordered by creation date (oldest first).

### Query parameters

| Parameter | Required | Type    | Description                                               |
| --------- | -------- | ------- | --------------------------------------------------------- |
| `limit`   | No       | integer | Maximum results per page. Default `50` (capped at `100`). |
| `cursor`  | No       | string  | Cursor for keyset pagination.                             |

### Response `200`

```json theme={null}
{
  "data": [
    {
      "id": "ds_001",
      "tenantId": "t_001",
      "key": "crm-customers",
      "name": "CRM Customer Export",
      "description": "Daily customer data export from Salesforce.",
      "connectorKey": "salesforce",
      "sourceConfig": {
        "objectName": "Contact",
        "query": "SELECT Id, Email, Name FROM Contact"
      },
      "fileFormat": null,
      "syncMode": "incremental",
      "schedule": {
        "cron": "0 2 * * *",
        "timezone": "America/New_York"
      },
      "schemaKey": "customers",
      "status": "active",
      "lastSyncAt": "2026-03-16T02:00:00.000Z",
      "lastSyncStatus": "success",
      "recordCount": 45000,
      "rowVersion": 3,
      "createdAt": "2026-03-01T12:00:00.000Z",
      "updatedAt": "2026-03-16T02:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 4,
    "limit": 50,
    "hasMore": false,
    "cursor": null
  }
}
```

***

## Create a data source

```
POST /api/v1/data-sources
```

Creates a new data source configuration.

### Request body

| Field            | Required | Type           | Description                                                                |
| ---------------- | -------- | -------------- | -------------------------------------------------------------------------- |
| `key`            | **Yes**  | string (1-255) | Unique identifier key.                                                     |
| `name`           | **Yes**  | string (1-255) | Display name.                                                              |
| `description`    | No       | string         | Description. Default `""`.                                                 |
| `connectorKey`   | No       | string         | Connector type key (e.g., `"s3"`, `"snowflake"`, `"kafka"`). Default `""`. |
| `sourceConfig`   | No       | object         | Connector-specific source configuration. Default `{}`.                     |
| `fileFormat`     | No       | string \| null | File format for file-based sources (e.g., `"csv"`, `"parquet"`, `"json"`). |
| `syncMode`       | No       | enum           | `full_refresh` (default), `incremental`, `cdc`.                            |
| `schedule`       | No       | object         | Sync schedule configuration. Default `{}`.                                 |
| `schemaKey`      | No       | string \| null | Target schema key for data loading.                                        |
| `status`         | No       | enum           | `draft` (default), `active`, `paused`, `archived`.                         |
| `lastSyncAt`     | No       | string \| null | ISO 8601 timestamp of last sync.                                           |
| `lastSyncStatus` | No       | string \| null | Last sync result (e.g., `"success"`, `"failed"`).                          |
| `recordCount`    | No       | integer (>= 0) | Number of records in the source. Default `0`.                              |

### Sync modes

| Mode           | Description                                       |
| -------------- | ------------------------------------------------- |
| `full_refresh` | Replace all data on each sync.                    |
| `incremental`  | Only sync new or changed records since last sync. |
| `cdc`          | Change data capture for real-time streaming.      |

### Example request

```json theme={null}
{
  "key": "crm-customers",
  "name": "CRM Customer Export",
  "description": "Daily customer data export from Salesforce.",
  "connectorKey": "salesforce",
  "sourceConfig": {
    "objectName": "Contact",
    "query": "SELECT Id, Email, Name FROM Contact"
  },
  "syncMode": "incremental",
  "schedule": {
    "cron": "0 2 * * *",
    "timezone": "America/New_York"
  },
  "schemaKey": "customers",
  "status": "active"
}
```

### Response `201`

Returns the created data source object.

### Error codes

| Code  | Reason                                      |
| ----- | ------------------------------------------- |
| `400` | Validation error (missing key or name).     |
| `409` | A data source with that key already exists. |
| `415` | `Content-Type` is not `application/json`.   |

***

## Update a data source

```
PUT /api/v1/data-sources
```

Updates an existing data source. Only provided fields are changed. Supports optimistic concurrency via `rowVersion`.

### Request body

| Field            | Required | Type           | Description                                      |
| ---------------- | -------- | -------------- | ------------------------------------------------ |
| `key`            | **Yes**  | string         | The data source key to update.                   |
| `name`           | No       | string (1-255) | Updated name.                                    |
| `description`    | No       | string         | Updated description.                             |
| `connectorKey`   | No       | string         | Updated connector key.                           |
| `sourceConfig`   | No       | object         | Updated source configuration.                    |
| `fileFormat`     | No       | string \| null | Updated file format.                             |
| `syncMode`       | No       | enum           | Updated sync mode.                               |
| `schedule`       | No       | object         | Updated schedule.                                |
| `schemaKey`      | No       | string \| null | Updated target schema key.                       |
| `status`         | No       | enum           | Updated status.                                  |
| `lastSyncAt`     | No       | string \| null | Updated last sync timestamp.                     |
| `lastSyncStatus` | No       | string \| null | Updated last sync status.                        |
| `recordCount`    | No       | integer (>= 0) | Updated record count.                            |
| `rowVersion`     | No       | integer        | Expected row version for optimistic concurrency. |

<Warning>
  If `rowVersion` is provided and does not match the current version, the update is rejected with a `409` conflict response containing the current data source state.
</Warning>

### Response `200`

Returns the updated data source object. The `rowVersion` is automatically incremented.

### Response `409` (concurrency conflict)

```json theme={null}
{
  "title": "Optimistic concurrency conflict",
  "detail": "rowVersion mismatch.",
  "current": { "...": "current data source object" }
}
```

### Error codes

| Code  | Reason                           |
| ----- | -------------------------------- |
| `400` | Validation error.                |
| `404` | Data source not found.           |
| `409` | Optimistic concurrency conflict. |

***

## Delete a data source

```
DELETE /api/v1/data-sources?key={sourceKey}
```

Deletes a data source by key.

### Query parameters

| Parameter | Required | Type   | Description                |
| --------- | -------- | ------ | -------------------------- |
| `key`     | **Yes**  | string | Data source key to delete. |

### Response `204`

Empty body on success.

### Error codes

| Code  | Reason                         |
| ----- | ------------------------------ |
| `400` | Missing `key` query parameter. |
| `404` | Data source not found.         |

***

## Role requirements

| Method | Minimum role           |
| ------ | ---------------------- |
| GET    | any authenticated user |
| POST   | `editor`               |
| PUT    | `editor`               |
| DELETE | `editor`               |

<Card title="Data Platform" icon="database" href="/data/overview">
  Learn more about connectors, schemas, and data pipelines in the platform UI.
</Card>