Skip to main content

​
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

ParameterTypeDescription
idstringSchema ID

​
Request Body

FieldTypeRequiredDescription
rowsobject[]YesArray 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

CodeReason
400Empty rows array or invalid column names
404Schema not found
500Database 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

ParameterTypeDescription
idstringSchema ID

​
Query Parameters

ParameterTypeDefaultDescription
limitinteger50Max rows to return (1-500)
offsetinteger0Pagination 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, "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

ParameterTypeDescription
idstringSchema 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

CodeReason
403Table name is not a schema-system table (missing ds_ prefix)
404Schema 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.
FieldTypeRequiredDescription
fileFileYesCSV file (max 50MB)

​
Limits

ConstraintValue
Max file size50 MB
Allowed typestext/csv, application/vnd.ms-excel, text/plain
Sample sizeFirst 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

CodeReason
400Missing file, no columns found, or CSV parse error
413File exceeds 50 MB limit
415Invalid file type (not CSV)

​
Roles

admin, editor

​
Role Summary

EndpointMethodAllowed Roles
/schemas/{id}/dataPOSTadmin, editor
/schemas/{id}/dataGETadmin, editor, viewer
/schemas/{id}/statsGETadmin, editor, viewer
/schemas/uploadPOSTadmin, editor
See also: Schemas | Data Platform