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

# Seed Datasets API

> List available sample datasets and load them into the platform for testing and demonstration.

The Seed Datasets API provides pre-built dataset packs that populate the platform with realistic sample data. Each pack includes schemas, categories, offers, channels, creatives, decisioning gates, contact policies, algorithm models, decision flows, segments, and synthetic customer/interaction data.

<Info>
  See the [Sample Data guide](/get-started/sample-data) for a walkthrough of using seed datasets.
</Info>

## Base path

```
/api/v1/seed-dataset
```

***

## List available datasets

```
GET /api/v1/seed-dataset
```

Returns all registered dataset packs with their metadata and current load status.

### Response `200`

```json theme={null}
{
  "datasets": [
    {
      "key": "retail-rewards",
      "name": "Retail Rewards Offers",
      "description": "Full NBA pipeline with retail rewards loyalty offers — multi-channel delivery, Thompson Bandit, segments.",
      "source": "kaggle",
      "csvFiles": [],
      "testingFocus": "Multi-channel loyalty offers with frequency capping",
      "schemaCount": 3,
      "offerCount": 10,
      "modelCount": 3,
      "channelCount": 6,
      "categoryCount": 3,
      "creativeCount": 60,
      "loaded": false
    }
  ],
  "currentlyLoaded": null
}
```

### Field reference

| Field             | Type           | Description                                                               |
| ----------------- | -------------- | ------------------------------------------------------------------------- |
| `key`             | string         | Unique dataset identifier used in load/delete URLs.                       |
| `name`            | string         | Human-readable dataset name.                                              |
| `description`     | string         | Short description of the dataset.                                         |
| `source`          | string         | Data source type (e.g., `"synthetic"`).                                   |
| `csvFiles`        | array          | List of CSV file paths included in the dataset pack.                      |
| `testingFocus`    | string         | What this dataset is best suited for testing.                             |
| `schemaCount`     | integer        | Number of data schemas in the pack.                                       |
| `offerCount`      | integer        | Number of offers in the pack.                                             |
| `modelCount`      | integer        | Number of algorithm models in the pack.                                   |
| `channelCount`    | integer        | Number of channels in the pack.                                           |
| `categoryCount`   | integer        | Number of categories in the pack.                                         |
| `creativeCount`   | integer        | Number of creatives in the pack.                                          |
| `loaded`          | boolean        | Whether this dataset is currently loaded for the tenant.                  |
| `currentlyLoaded` | string \| null | Key of the currently loaded dataset, or `null` if none (top-level field). |

***

## Load a dataset

```
POST /api/v1/seed-dataset/{key}
```

Loads a dataset pack into the platform. Creates all entities in correct foreign-key dependency order: schemas, categories, channels, offers, creatives, rules, models, decision flows, segments, synthetic data rows, and interaction history.

### Path parameters

| Parameter | Required | Type   | Description                             |
| --------- | -------- | ------ | --------------------------------------- |
| `key`     | **Yes**  | string | Dataset key (e.g., `"retail-rewards"`). |

### Query parameters

| Parameter | Required | Type   | Description                                            |
| --------- | -------- | ------ | ------------------------------------------------------ |
| `force`   | No       | string | Set to `"true"` to replace a currently loaded dataset. |

### Response `202`

Loading is **asynchronous**. The request returns immediately with a `202 Accepted`
and a `pollUrl`; the schemas, entities, synthetic rows, and interaction history are
created in the background. Poll the [status endpoint](#poll-seed-progress) to track
progress and read the final per-entity `counts` once `status` is `"complete"`.

```json theme={null}
{
  "status": "loading",
  "message": "Dataset loading in background...",
  "pollUrl": "/api/v1/seed-dataset/retail-rewards/status"
}
```

### Error codes

| Code  | Reason                                                            |
| ----- | ----------------------------------------------------------------- |
| `404` | Dataset key not found in registry.                                |
| `409` | Another dataset is already loaded (use `?force=true` to replace). |
| `409` | Same dataset is already loaded.                                   |
| `429` | Rate limited (5 requests per 60 seconds).                         |

### Response `409` (dataset conflict)

```json theme={null}
{
  "status": 409,
  "currentlyLoaded": "banking-e2e",
  "requestedLoad": "retail-rewards",
  "message": "Banking NBA is currently loaded. Add ?force=true to remove it and load Retail Rewards."
}
```

***

## Remove a dataset

```
DELETE /api/v1/seed-dataset/{key}
```

Removes all entities belonging to a dataset pack in reverse foreign-key dependency order. Drops associated PostgreSQL tables and segment views.

### Path parameters

| Parameter | Required | Type   | Description            |
| --------- | -------- | ------ | ---------------------- |
| `key`     | **Yes**  | string | Dataset key to remove. |

### Response `200`

The `message` is always the literal string `"Dataset removed"`. An optional
`warnings` array is included only when part of the entity cleanup failed.

```json theme={null}
{
  "message": "Dataset removed",
  "counts": {
    "interactions": 500,
    "interactionSummaries": 500,
    "creatives": 24,
    "offers": 12,
    "experiments": 1,
    "decisionFlows": 1,
    "channels": 4,
    "categories": 3,
    "qualificationRules": 5,
    "contactPolicies": 3,
    "models": 2,
    "runs": 0,
    "segments": 1,
    "schemas": 2
  }
}
```

### Error codes

| Code  | Reason                             |
| ----- | ---------------------------------- |
| `404` | Dataset key not found in registry. |

***

## Upload CSV data

```
POST /api/v1/seed-dataset/{key}/upload
```

Upload a CSV file to replace the data in a specific schema table belonging to a loaded dataset. The existing rows in the target table are truncated before inserting the new data. Each CSV row is transformed into the correct schema format by the dataset pack's row-mapper.

### Path parameters

| Parameter | Required | Type   | Description                             |
| --------- | -------- | ------ | --------------------------------------- |
| `key`     | **Yes**  | string | Dataset key (e.g., `"retail-rewards"`). |

### Request body (multipart/form-data)

| Field    | Required | Type   | Description                                            |
| -------- | -------- | ------ | ------------------------------------------------------ |
| `file`   | **Yes**  | File   | CSV file to upload. Maximum size: 50 MB.               |
| `schema` | **Yes**  | string | Target schema name (must be part of the dataset pack). |

### Example

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/seed-dataset/retail-rewards/upload \
  -H "X-Tenant-Id: my-tenant" \ \
  -F "file=@customers.csv" \
  -F "schema=retail_customers"
```

### Response `200`

```json theme={null}
{
  "message": "Uploaded 5000 rows to retail_customers",
  "rowsInserted": 5000,
  "schemaName": "retail_customers",
  "datasetKey": "retail-rewards"
}
```

### Error codes

| Code  | Reason                                                         |
| ----- | -------------------------------------------------------------- |
| `400` | Missing `file` or `schema` form field.                         |
| `400` | Schema name not part of the dataset pack.                      |
| `400` | Schema not loaded in the database (load the dataset first).    |
| `400` | CSV parse error.                                               |
| `400` | No valid rows after mapping.                                   |
| `400` | Dataset does not support CSV upload (no `mapCsvRow` function). |
| `404` | Dataset key not found in registry.                             |
| `413` | File exceeds 50 MB size limit.                                 |
| `429` | Rate limited (5 requests per 60 seconds).                      |

***

## Poll seed progress

```
GET /api/v1/seed-dataset/:key/status
```

Read the current seeding status for an in-flight or completed `Load a dataset` call. The endpoint reads the per-tenant seed-progress entry from platform settings (keyed by `(tenantId, "seed", "seed_progress")`) and returns its parsed value. When no progress entry exists the endpoint returns the idle baseline so the UI does not need to handle a missing-row case.

### Path Parameters

| Parameter | Type   | Description                                                                                                   |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| `key`     | string | Dataset key (e.g., `"retail-rewards"`). Currently informational — the row key is per-tenant, not per-dataset. |

### Response — In flight

```json theme={null}
{
  "status": "loading",
  "step": "Building interaction history (500 records across 30 days)",
  "progress": 80
}
```

When `status` becomes `"complete"` the row also carries a `counts` object (per-entity
row counts) and, if any step logged a non-fatal issue, a `warnings` array.

### Response — Idle (no seed in progress, or row missing)

Returned at `route.ts:29-33` and `route.ts:39-43`.

```json theme={null}
{
  "status": "idle",
  "step": "",
  "progress": 0
}
```

<ResponseField name="status" type="string">
  State written by the seed orchestrator. The values it emits are `"idle"` (baseline when no row exists), `"loading"` (in flight), `"complete"` (finished), and `"error"` (failed). The route does not validate the set — whatever the orchestrator wrote into `PlatformSetting.value` is returned as-is.
</ResponseField>

<ResponseField name="step" type="string">
  Human-readable label for the current step. Empty string when idle.
</ResponseField>

<ResponseField name="progress" type="number">
  Integer 0-100 reflecting per-step progress. Always `0` when idle.
</ResponseField>

### Status codes

| Code      | When                                           | Source            |
| --------- | ---------------------------------------------- | ----------------- |
| 200       | Returns the progress object (or idle baseline) | `route.ts:37, 42` |
| 401 / 403 | Caller fails authentication or role check      | `route.ts:18`     |

### Roles

admin, editor, viewer.

<Note>
  Polling cadence is up to the caller. The seed orchestrator updates the row at every step boundary — sub-second polls will see no change between updates. A 1-2 second interval is sufficient for the UI progress bar.
</Note>

***

## Role requirements

| Method | Minimum role |
| ------ | ------------ |
| GET    | `admin`      |
| POST   | `admin`      |
| DELETE | `admin`      |

<Warning>
  Loading a dataset creates real PostgreSQL tables with synthetic data rows. In a production environment, only use this for testing purposes.
</Warning>