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.
POST /api/v1/schemas//data
Insert rows into a schema’s underlying PostgreSQL table. Uses ON CONFLICT DO NOTHING to skip duplicate rows when a unique constraint exists.
Path Parameters
| Parameter | Type | Description |
|---|
id | string | Schema ID |
Request Body
| Field | Type | Required | Description |
|---|
rows | object[] | Yes | Array of row objects. Each key must match a column name in the schema. Min 1 row. |
Example
{
"rows": [
{ "customer_id": "C001", "full_name": "Alice Smith", "age": 30, "balance": 15000.50 },
{ "customer_id": "C002", "full_name": "Bob Jones", "age": 45, "balance": 82000.00 }
]
}
Response — 201 Created
{
"inserted": 2,
"tableName": "ds_customers_abc123"
}
Error Codes
| Code | Reason |
|---|
400 | Empty rows array or invalid column names |
404 | Schema not found |
500 | Database insert failure |
Roles
admin, editor
GET /api/v1/schemas//data
Preview rows from a schema’s underlying PostgreSQL table. Only works for tables created by the schema system (tables with ds_ prefix).
Path Parameters
| Parameter | Type | Description |
|---|
id | string | Schema ID |
Query Parameters
| Parameter | Type | Default | Description |
|---|
limit | integer | 50 | Max rows to return (1-500) |
offset | integer | 0 | Pagination offset |
Response
{
"total": 5000,
"limit": 50,
"offset": 0,
"rows": [
{
"id": 1,
"customer_id": "CUST001",
"age": 35,
"credit_score": 740,
"segment": "high_value"
}
]
}
{ "total": 0, "rows": [] }.
Roles
admin, editor, viewer
GET /api/v1/schemas//stats
Returns per-field statistics for a schema’s data. Results are cached for 5 minutes.
Path Parameters
| Parameter | Type | Description |
|---|
id | string | Schema ID |
Response
{
"fields": [
{
"name": "age",
"type": "numeric",
"min": 18,
"max": 85,
"avg": 42.3,
"distinctCount": 68
},
{
"name": "segment",
"type": "text",
"distinctCount": 4,
"topValues": ["high_value", "medium_value", "low_value", "new"]
}
],
"totalRows": 5000,
"cachedAt": "2026-03-30T12:00:00.000Z"
}
Field Stat Types
Numeric fields include: min, max, avg, distinctCount
Text fields include: distinctCount, topValues (top 5 by frequency)
Error Codes
| Code | Reason |
|---|
403 | Table name is not a schema-system table (missing ds_ prefix) |
404 | Schema not found |
Roles
admin, editor, viewer
POST /api/v1/schemas/upload
Upload a CSV file to infer column names and types. Does not create a schema or import data — only analyzes the file structure. Useful for building schema creation forms from uploaded files.
Request
Multipart form data with a single file field.
| Field | Type | Required | Description |
|---|
file | File | Yes | CSV file (max 50MB) |
Limits
| Constraint | Value |
|---|
| Max file size | 50 MB |
| Allowed types | text/csv, application/vnd.ms-excel, text/plain |
| Sample size | First 1 MB of file, up to 100 rows |
Example
curl -X POST https://playground.kaireonai.com/api/v1/schemas/upload \
-H "X-Tenant-Id: my-tenant" \
-F "file=@customers.csv"
Response
{
"columns": [
{ "name": "customer_id", "dataType": "varchar", "length": 50, "isNullable": true, "isPrimaryKey": false, "isUnique": false, "defaultValue": null },
{ "name": "age", "dataType": "integer", "isNullable": true, "isPrimaryKey": false, "isUnique": false, "defaultValue": null },
{ "name": "email", "dataType": "varchar", "length": 255, "isNullable": true, "isPrimaryKey": false, "isUnique": false, "defaultValue": null },
{ "name": "balance", "dataType": "numeric", "isNullable": true, "isPrimaryKey": false, "isUnique": false, "defaultValue": null }
],
"rowCount": 100,
"headers": ["customer_id", "age", "email", "balance"]
}
Error Codes
| Code | Reason |
|---|
400 | Missing file, no columns found, or CSV parse error |
413 | File exceeds 50 MB limit |
415 | Invalid file type (not CSV) |
Roles
admin, editor
Role Summary
| Endpoint | Method | Allowed Roles |
|---|
/schemas/{id}/data | POST | admin, editor |
/schemas/{id}/data | GET | admin, editor, viewer |
/schemas/{id}/stats | GET | admin, editor, viewer |
/schemas/upload | POST | admin, editor |
