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.
GET /api/v1/schemas
List all schemas with their fields. Supports cursor-based pagination.
Query Parameters
| Parameter | Type | Default | Description |
|---|
limit | integer | 20 | Max results per page |
cursor | string | — | Cursor for pagination |
Response
{
"data": [
{
"id": "schema_001",
"tenantId": "tenant_001",
"name": "customers",
"displayName": "Customers",
"description": "Core customer entity",
"tableName": "ds_customers",
"entityType": "customer",
"schemaType": "customer",
"status": "active",
"linkedSchemaId": null,
"joinMapping": null,
"summaryColumns": null,
"autoEnrich": false,
"fields": [
{
"id": "field_001",
"schemaId": "schema_001",
"name": "email",
"displayName": "Email",
"dataType": "varchar",
"length": 255,
"precision": null,
"scale": null,
"isNullable": false,
"isPrimaryKey": false,
"isUnique": true,
"isPredictor": false,
"defaultValue": null,
"description": "",
"ordinal": 1
}
],
"createdAt": "2026-01-10T08:00:00.000Z",
"updatedAt": "2026-01-10T08:00:00.000Z"
}
],
"pagination": {
"total": 5,
"hasMore": false,
"limit": 50,
"cursor": null
}
}
POST /api/v1/schemas
Create a new schema. This creates both a metadata record and a real PostgreSQL table via DDL.
Creating a schema executes CREATE TABLE against the database. If the DDL fails, the metadata record is automatically rolled back.
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Schema name (auto-sanitized to lowercase alphanumeric + underscores) |
displayName | string | Yes | Human-readable name |
description | string | No | Description |
entityType | string | No | Entity type: "customer", "account", "custom". Default: "custom" |
schemaType | string | No | Schema type: "customer", "transaction", "event", etc. Default: "customer" |
linkedSchemaId | string | No | ID of a customer-type schema to link to (must be in the same tenant) |
joinMapping | object | No | Join configuration for linking to the parent schema |
summaryColumns | array | No | Column names to display in summary views. Default: [] |
autoEnrich | boolean | No | Whether to auto-enrich from this schema during decision flows. Default: false |
fields | array | No | Initial field definitions (see field object below) |
Field Object
| Field | Type | Default | Description |
|---|
name | string | — | Column name |
displayName | string | name | Display label |
dataType | string | "varchar" | PostgreSQL data type |
length | integer | null | Length for varchar/char types |
precision | integer | null | Precision for decimal types |
scale | integer | null | Scale for decimal types |
isNullable | boolean | true | Whether the column allows NULL |
isPrimaryKey | boolean | false | Primary key constraint |
isUnique | boolean | false | Unique constraint |
defaultValue | string | null | Default value expression |
description | string | "" | Field description |
Example
curl -X POST https://playground.kaireonai.com/api/v1/schemas \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-d '{
"name": "customers",
"displayName": "Customers",
"entityType": "customer",
"fields": [
{ "name": "email", "dataType": "varchar", "length": 255, "isUnique": true },
{ "name": "loan_amount", "dataType": "decimal", "precision": 12, "scale": 2 },
{ "name": "tenure_months", "dataType": "integer" }
]
}'
201 Created
PUT /api/v1/schemas
Update an existing schema’s metadata. Only provided fields are changed. This does not modify the underlying PostgreSQL table structure — use the field endpoints for DDL changes.
Request Body
| Field | Type | Required | Description |
|---|
id | string | Yes | Schema ID to update |
displayName | string | No | Updated display name |
description | string | No | Updated description |
entityType | string | No | Updated entity type |
schemaType | string | No | Updated schema type |
linkedSchemaId | string | No | Updated linked schema ID (must reference a customer-type schema in the same tenant) |
joinMapping | object | No | Updated join configuration |
summaryColumns | array | No | Updated summary columns |
autoEnrich | boolean | No | Updated auto-enrich flag |
200 OK with the updated schema object including fields.
Error Codes
| Code | Reason |
|---|
400 | Missing id, or linkedSchemaId references an invalid schema |
404 | Schema not found |
DELETE /api/v1/schemas
Delete a schema and drop its backing PostgreSQL table.
Query Parameters
| Parameter | Type | Required | Description |
|---|
id | string | Yes | Schema ID to delete |
This drops the underlying database table. All data in the table is permanently lost.
204 No Content
POST /api/v1/schemas/fields
Add a column to an existing schema. Executes ALTER TABLE ADD COLUMN.
Request Body
| Field | Type | Required | Description |
|---|
schemaId | string | Yes | Parent schema ID |
name | string | Yes | Column name |
dataType | string | Yes | PostgreSQL data type |
displayName | string | No | Display label |
length | integer | No | Length for varchar/char |
precision | integer | No | Precision for decimal |
scale | integer | No | Scale for decimal |
isNullable | boolean | No | Default: true |
isPrimaryKey | boolean | No | Default: false |
isUnique | boolean | No | Default: false |
defaultValue | string | No | Default value expression |
description | string | No | Field description |
201 Created with the field object.
DELETE /api/v1/schemas/fields
Remove a column from a schema. Executes ALTER TABLE DROP COLUMN.
Query Parameters
| Parameter | Type | Required | Description |
|---|
fieldId | string | Yes | Field ID to delete |
This drops the column from the underlying table. Data in this column is permanently lost.
204 No Content
Roles
| Endpoint | Allowed Roles |
|---|
GET /schemas | admin, editor, viewer |
POST /schemas | admin, editor |
PUT /schemas | admin, editor |
DELETE /schemas | admin, editor |
POST /schemas/fields | admin, editor |
DELETE /schemas/fields | admin, editor |
