Schema Data & Stats

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. Between 1 and 5000 rows per request.

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,
  "skipped": 0,
  "tableName": "ds_customers_abc123"
}

inserted is the number of rows actually written (from Postgres’ affected-row count), and skipped is the number dropped by ON CONFLICT DO NOTHING (duplicate rows against a unique constraint). inserted + skipped equals the number of valid rows submitted.

Error Codes

Code	Reason
`400`	Empty `rows` array, more than 5000 rows, per-table 5000-record limit exceeded, or the schema has no user-defined fields configured
`403`	The schema’s backing table is outside the schema system (missing `ds_` prefix)
`404`	Schema not found
`429`	Rate limited (20 requests per 60 seconds)
`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"
    }
  ]
}

If the table does not exist yet (no data seeded), returns { "total": 0, "limit": <limit>, "offset": <offset>, "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

​POST /api/v1/schemas//data

​Path Parameters

​Request Body

​Example

​Response — 201 Created

​Error Codes

​Roles

​GET /api/v1/schemas//data

​Path Parameters

​Query Parameters

​Response

​Roles

​GET /api/v1/schemas//stats

​Path Parameters

​Response

​Field Stat Types

​Error Codes

​Roles

​POST /api/v1/schemas/upload

​Request

​Limits

​Example

​Response

​Error Codes

​Roles

​Role Summary

POST /api/v1/schemas//data

Path Parameters

Request Body

Example

Response — `201 Created`

Error Codes

Roles

GET /api/v1/schemas//data

Path Parameters

Query Parameters

Response

Roles

GET /api/v1/schemas//stats

Path Parameters

Response

Field Stat Types

Error Codes

Roles

POST /api/v1/schemas/upload

Request

Limits

Example

Response

Error Codes

Roles

Role Summary