Skip to main content

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.

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, qualification rules, 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": "starbucks",
      "name": "Starbucks Offers",
      "description": "Full NBA pipeline with Starbucks 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

FieldTypeDescription
keystringUnique dataset identifier used in load/delete URLs.
namestringHuman-readable dataset name.
descriptionstringShort description of the dataset.
sourcestringData source type (e.g., "synthetic").
csvFilesarrayList of CSV file paths included in the dataset pack.
testingFocusstringWhat this dataset is best suited for testing.
schemaCountintegerNumber of data schemas in the pack.
offerCountintegerNumber of offers in the pack.
modelCountintegerNumber of algorithm models in the pack.
channelCountintegerNumber of channels in the pack.
categoryCountintegerNumber of categories in the pack.
creativeCountintegerNumber of creatives in the pack.
loadedbooleanWhether this dataset is currently loaded for the tenant.
currentlyLoadedstring | nullKey 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

ParameterRequiredTypeDescription
keyYesstringDataset key (e.g., "starbucks").

​
Query parameters

ParameterRequiredTypeDescription
forceNostringSet to "true" to replace a currently loaded dataset.

​
Response 201

{
  "message": "Starbucks Rewards loaded successfully",
  "counts": {
    "schemas": 2,
    "categories": 3,
    "subCategories": 6,
    "channels": 4,
    "offers": 12,
    "creatives": 24,
    "qualificationRules": 5,
    "contactPolicies": 3,
    "outcomeTypes": 10,
    "models": 2,
    "experiments": 1,
    "decisionFlows": 1,
    "segments": 1,
    "customers_rows": 1000,
    "transactions_rows": 1000,
    "interactions": 500,
    "interactionSummaries": 500,
    "segmentCustomers": 450
  },
  "datasetKey": "starbucks"
}

​
Error codes

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

​
Response 409 (dataset conflict)

{
  "status": 409,
  "currentlyLoaded": "banking",
  "requestedLoad": "starbucks",
  "message": "Banking NBA is currently loaded. Add ?force=true to remove it and load Starbucks 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

ParameterRequiredTypeDescription
keyYesstringDataset key to remove.

​
Response 200

{
  "message": "Starbucks Rewards removed successfully",
  "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

CodeReason
404Dataset 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. The dataset’s mapCsvRow() function transforms each CSV row into the correct schema format.

​
Path parameters

ParameterRequiredTypeDescription
keyYesstringDataset key (e.g., "starbucks").

​
Request body (multipart/form-data)

FieldRequiredTypeDescription
fileYesFileCSV file to upload. Maximum size: 50 MB.
schemaYesstringTarget schema name (must be part of the dataset pack).

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/seed-dataset/starbucks/upload \
  -H "X-Tenant-Id: my-tenant" \
  -H "X-User-Role: admin" \
  -F "file=@customers.csv" \
  -F "schema=starbucks_customers"

​
Response 200

{
  "message": "Uploaded 5000 rows to starbucks_customers",
  "rowsInserted": 5000,
  "schemaName": "starbucks_customers",
  "datasetKey": "starbucks"
}

​
Error codes

CodeReason
400Missing file or schema form field.
400Schema name not part of the dataset pack.
400Schema not loaded in the database (load the dataset first).
400CSV parse error.
400No valid rows after mapping.
400Dataset does not support CSV upload (no mapCsvRow function).
404Dataset key not found in registry.
413File exceeds 50 MB size limit.
429Rate 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 route at src/app/api/v1/seed-dataset/[key]/status/route.ts:14-45 reads PlatformSetting row keyed by (tenantId, "seed", "seed_progress") and parses its JSON value. When no row exists the route returns the idle baseline so the UI does not need to handle a missing-row case.

​
Path Parameters

ParameterTypeDescription
keystringDataset key (e.g., "starbucks"). Currently informational — the row key is per-tenant, not per-dataset.

​
Response — In flight

{
  "status": "running",
  "step": "Loading interaction history",
  "progress": 65
}

​
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
}
​
status
string
Operator-defined state from the seed orchestrator. Common values: "idle", "running", "completed", "failed". The route does not validate the set — whatever the orchestrator wrote into PlatformSetting.value is returned as-is.
​
step
string
Human-readable label for the current step. Empty string when idle.
​
progress
number
Integer 0-100 reflecting per-step progress. Always 0 when idle.

​
Status codes

CodeWhenSource
200Returns the progress object (or idle baseline)route.ts:37, 42
401 / 403Caller fails authentication or role checkroute.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

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