Schemas, fields, endpoints, rules

Requires a platform JWT or PAT:

Authorization: Bearer <platform JWT or kfx_ PAT>

Paths below are under /api/projects/:projectId. Missing or non-Bearer auth is 401 { "success": false, "message": "Authentication required" }. A bad token is 401 "Invalid or expired token". A service token or any other non-platform credential is 403 "Platform authentication required". A kfxr_ runner token fails that same check on these paths.

Successful creates and the endpoint toggle are 200. data is the object itself. List routes return a JSON array as data.

A missing permission is 404 "Project not found" (or a more specific not-found string).

Schemas and fields

Method	Path	Description
GET/POST	/schemas	List / create tables
GET/PUT/DELETE	/schemas/:schemaId	Manage a schema
GET/POST	/schemas/:schemaId/fields	List / create fields (referencedSchemaId or referencedCollection optional on reference fields)
PUT/DELETE	/schemas/:schemaId/fields/:fieldId	Update / delete field
POST	/schemas/:schemaId/fields/reorder	Reorder fields
GET	/export/models	Export Dart models

Endpoints and rules

Method	Path	Description
GET/POST	/schemas/:schemaId/endpoints	List / create endpoint configs
PUT/DELETE	/schemas/:schemaId/endpoints/:endpointId	Toggle / delete
GET/POST	/endpoints/:endpointId/rules	List / create rules
PUT/DELETE	/endpoints/:endpointId/rules/:ruleId	Update / delete
POST	/endpoints/:endpointId/rules/reorder	Reorder

Project auth and data (admin)

Method	Path	Description
POST	/auth/toggle	Enable/disable end-user auth
POST	/users/:userId/token	Mint a project-user JWT
GET/POST	/files	Project file metadata (list)
POST	/query	Execute a WidgetQuery
GET/POST	/webhooks	List / create Data API webhooks
GET/PATCH/DELETE	/webhooks/:id	Manage a webhook
GET	/webhooks/:id/deliveries	Recent deliveries
POST	/webhooks/:id/ping	Send webhook.ping

Table row admin (console data browser) uses dedicated table-data routes on the admin SDK (tableData), not the public /api/p client SDK.

See Collections, Endpoints, Access rules, Webhooks.

Create schema

POST /api/projects/:projectId/schemas

The handler reads only name (required string). An empty name is 400 "name is required".

{ "name": "notes" }

200

{
  "success": true,
  "data": {
    "id": "<uuid>",
    "projectId": "<project uuid>",
    "name": "notes",
    "createdAt": "<ISO-8601>",
    "updatedAt": "<ISO-8601>"
  }
}

The create also inserts one endpoint per method (list, get, create, update, delete, upload, download, fileDelete), enabled by default. Those rows are not in this response. List endpoints to obtain ids for the toggle.

404 "Project not found" when the caller lacks schemas.create or the project does not exist.

429 when the collection cap is hit and plan limits are wired. limit_key is max_collections. message is the plan-catalog text. limit and current are omitted when the service does not pass them.

{
  "success": false,
  "message": "<plan-limit text>",
  "code": "quota_exceeded",
  "limit_key": "max_collections",
  "limit": 0,
  "current": 0
}

402 { "success": false, "message": "...", "code": "payment_required" } when the billing gate blocks the account. limit_key is optional on that body.

Add field

POST /api/projects/:projectId/schemas/:schemaId/fields

Key	Handling
name	Required string.
fieldType	Required string.
isRequired	Bool, default false.
defaultValue	String, or omitted.
isArray	Bool, default false.
orderIndex	Int, default 0.
referencedSchemaId	Optional string.
referencedCollection	Optional string.

Missing name or fieldType is 400 "name and fieldType are required".

The write stores fieldType as given. Values the product uses are string, number, boolean, datetime, array, map, reference, and file. For reference, set referencedSchemaId or referencedCollection (the collection name). Empty reference targets on a non-reference field are ignored.

A bad target is 400 "referencedSchemaId is not a collection in this project", "referencedCollection does not match referencedSchemaId", or Unknown collection "<name>". A Mongo system name is 400 Field name "<name>" is reserved (MongoDB system field).

{
  "name": "title",
  "fieldType": "string",
  "isRequired": true
}

200

{
  "success": true,
  "data": {
    "id": "<uuid>",
    "tableSchemaId": "<schema uuid>",
    "name": "title",
    "fieldType": "string",
    "isRequired": true,
    "defaultValue": null,
    "isArray": false,
    "orderIndex": 0,
    "referencedSchemaId": null,
    "referencedCollection": null
  }
}

referencedSchemaId and referencedCollection are always present. referencedCollection is the target schema’s name when referencedSchemaId resolves in the project; otherwise null.

404 "Schema not found" or "Project not found".

Toggle endpoint

PUT /api/projects/:projectId/schemas/:schemaId/endpoints/:endpointId

This is PUT. The handler reads only enabled (bool, required). 400 "enabled is required" when it is missing or not a bool.

{ "enabled": false }

200

{
  "success": true,
  "data": {
    "id": "<endpoint uuid>",
    "tableSchemaId": "<schema uuid>",
    "method": "list",
    "enabled": false
  }
}

method is the value stored when the endpoint was created (list, get, create, update, delete, upload, download, fileDelete for the rows schema create inserts). The toggle does not accept method.

404 "Endpoint not found" or "Project not found" (permission endpoints.write).

POST /api/projects/:projectId/schemas/:schemaId/endpoints reads method (required) and enabled (default true) and returns the same four keys. That create stores method as given.

Create rule

POST /api/projects/:projectId/endpoints/:endpointId/rules

Key	Handling
ruleType	Required string.
ruleConfig	Any JSON, passed through after normalization.
orderIndex	Int, default 0.

400 "ruleType is required" when ruleType is missing.

Valid ruleType values: requireAuth, requireServiceToken, userFieldCompare, fieldInBody, fileSizeLimit, fileMimeType, fileExtensionAllow. An unknown type is 400 Unknown ruleType "<type>". Valid: .... Snake-case aliases such as require_auth are accepted and stored as the camelCase value.

Empty config is valid for requireAuth and requireServiceToken:

{
  "ruleType": "requireAuth",
  "ruleConfig": {}
}

200

{
  "success": true,
  "data": {
    "id": "<uuid>",
    "endpointConfigId": "<endpoint uuid>",
    "ruleType": "requireAuth",
    "ruleConfig": {},
    "orderIndex": 0
  }
}

userFieldCompare needs ruleConfig keys userField, operator, and compareWith (record or value), plus recordField or value. Operators are eq, neq, gt, gte, lt, lte, in, and contains. See Access rules for the other rule types.

404 "Endpoint not found" or "Project not found" (permission rules.write).