Seed Datasets API - KaireonAI

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.

See the Sample Data guide for a walkthrough of using seed datasets.

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`

{
  "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 to track progress and read the final per-entity counts once status is "complete".

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

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

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

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`

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

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

{
  "status": "idle",
  "step": "",
  "progress": 0
}

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.

string

Human-readable label for the current step. Empty string when idle.

number

Integer 0-100 reflecting per-step progress. Always 0 when idle.

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.

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.

Role requirements

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

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

​Base path

​List available datasets

​Response 200

​Field reference

​Load a dataset

​Path parameters

​Query parameters

​Response 202

​Error codes

​Response 409 (dataset conflict)

​Remove a dataset

​Path parameters

​Response 200

​Error codes

​Upload CSV data

​Path parameters

​Request body (multipart/form-data)

​Example

​Response 200

​Error codes

​Poll seed progress

​Path Parameters

​Response — In flight

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

​Status codes

​Roles

​Role requirements

Base path

List available datasets

Response `200`

Field reference

Load a dataset

Path parameters

Query parameters

Response `202`

Error codes

Response `409` (dataset conflict)

Remove a dataset

Path parameters

Response `200`

Error codes

Upload CSV data

Path parameters

Request body (multipart/form-data)

Example

Response `200`

Error codes

Poll seed progress

Path Parameters

Response — In flight

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

Status codes

Roles

Role requirements