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",
"name": "customers",
"displayName": "Customers",
"description": "Core customer entity",
"tableName": "kd_customers",
"entityType": "customer",
"status": "active",
"fields": [
{
"id": "field_001",
"name": "email",
"displayName": "Email",
"dataType": "varchar",
"length": 255,
"isNullable": false,
"isPrimaryKey": false,
"isUnique": true,
"ordinal": 1
}
],
"createdAt": "2026-01-10T08:00:00.000Z"
}
],
"total": 5,
"hasMore": false
}
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" |
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
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 |
DELETE /schemas | admin, editor |
POST /schemas/fields | admin, editor |
DELETE /schemas/fields | admin, editor |
