Database API

2026-10-20

Database API
数据库
数据表
字段
事件
读写行
错误码

Database API

（待译）

Database is a headless content store: structured tables and rows that people, agents and scripts read and write directly through the API, the way a headless CMS works. Concepts and behavior follow Supabase (PostgREST filters, projections, ordering and row writes via supabase-js), so Supabase experience applies. Differences: storage uses SQLite, not PostgreSQL, and schema changes use table/field APIs rather than SQL migrations or raw SQL; access uses a Praxis credential scoped to its tenant, with no Supabase Auth or row-level security policies; realtime row subscriptions are unavailable; casts, aggregates, spread and join modifiers are unsupported, and filtered planned/estimated counts may be unknown; upsert targets id or one unique field rather than composite keys. For an application's own runtime data, use the application's own d1, kv or r2 components instead. Start with praxis.database.databases.create to create a database, then use its returned id for tables and rows.

用 API Key 作为 Bearer 凭据，通过以下地址管理库与表结构。

https://api.deepraxis.ai/database/v1

指南 →

资源	路径
Databases	/database/v1/databases
Tables	/database/v1/databases/{database_id}/tables
Fields	/database/v1/databases/{database_id}/tables/{table}/fields
Events	/database/v1/databases/{database_id}/events
REST	/database/v1/databases/{database_id}/rest/{table}

错误码

数据库

指南 →

基础地址与鉴权

创建库

POST /database/v1/databases

请求体

字段	类型	必填	说明
name	string	是	名称
labels	object	否	标签

返回: Database.

响应

HTTP 201

Success

application/json

名称	类型	说明
id	string	Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path.
name	string	Display name given at creation or by the last update; it is not an identifier.
labels	object	String tags attached to the database, as key and value pairs; empty object when none.
status	string	Lifecycle state of the database. Table, field and row calls work only while it is active.
table_count	integer	Number of tables currently in the database, at most 50; refreshed when the schema changes.
size_bytes	integer	Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately.
created_at	string	Time the database was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp.
deleted_at	string \| null	Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore.
purge_at	string \| null	Permanent deletion deadline for deleting databases; null otherwise.

curl -X POST "https://api.deepraxis.ai/database/v1/databases" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"walk-lib-r1-DOC-5320-tasks","labels":{"purpose":"docs","sample":"walk-lib-r1-doc-5320-"}}'

响应示例 — HTTP 201

{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-tasks",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:41.488Z",
  "deleted_at": null,
  "purge_at": null
}

列出库

GET /database/v1/databases

参数	位置	说明
cursor	query	上一页返回的 next_cursor。
limit	query	最多返回的条数。 (default: 20) (1–100)
labels	query	精确匹配标签，例如 labels[purpose]=docs。
status	query	库状态：active 或 deleting；省略时只列出 active。

返回: Page + object.

响应

HTTP 200

Success

application/json

名称	类型	说明
data	array<object>	Databases on this page, newest first (created_at descending, ties by id). Deleting databases are excluded unless status=deleting.
data[].id	string	Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path.
data[].name	string	Display name given at creation or by the last update; it is not an identifier.
data[].labels	object	String tags attached to the database, as key and value pairs; empty object when none.
data[].status	string	Lifecycle state of the database. Table, field and row calls work only while it is active.
data[].table_count	integer	Number of tables currently in the database, at most 50; refreshed when the schema changes.
data[].size_bytes	integer	Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately.
data[].created_at	string	Time the database was created, as an RFC 3339 UTC timestamp.
data[].updated_at	string	Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp.
data[].deleted_at	string \| null	Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore.
data[].purge_at	string \| null	Permanent deletion deadline for deleting databases; null otherwise.
next_cursor	string \| null	Opaque cursor for the next page, or null when there are no more items. Databases list: pass it as cursor. Events list: pass it as after_seq (order asc) or before_seq (order desc).

curl -g -X GET "https://api.deepraxis.ai/database/v1/databases?limit=10&labels[purpose]=docs&labels[sample]=walk-lib-r1-doc-5320-" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "data": [
    {
      "id": "db_d6f0d743d5a645e8",
      "name": "walk-lib-r1-DOC-5320-tasks",
      "labels": {
        "purpose": "docs",
        "sample": "walk-lib-r1-doc-5320-"
      },
      "status": "active",
      "table_count": 0,
      "size_bytes": 53248,
      "created_at": "2026-10-11T17:41:40.620Z",
      "updated_at": "2026-10-11T17:41:41.488Z",
      "deleted_at": null,
      "purge_at": null
    }
  ],
  "next_cursor": null
}

读取库

GET /database/v1/databases/{database_id}

参数	位置	说明
database_id	path	库 ID。

返回: Database.

响应

HTTP 200

Success

application/json

名称	类型	说明
id	string	Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path.
name	string	Display name given at creation or by the last update; it is not an identifier.
labels	object	String tags attached to the database, as key and value pairs; empty object when none.
status	string	Lifecycle state of the database. Table, field and row calls work only while it is active.
table_count	integer	Number of tables currently in the database, at most 50; refreshed when the schema changes.
size_bytes	integer	Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately.
created_at	string	Time the database was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp.
deleted_at	string \| null	Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore.
purge_at	string \| null	Permanent deletion deadline for deleting databases; null otherwise.

curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-tasks",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:41.488Z",
  "deleted_at": null,
  "purge_at": null
}

更新库

PATCH /database/v1/databases/{database_id}

参数	位置	说明
database_id	path	库 ID。

请求体

字段	类型	必填	说明
name	string	否	名称
labels	object	否	标签

返回: Database.

响应

HTTP 200

Success

application/json

名称	类型	说明
id	string	Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path.
name	string	Display name given at creation or by the last update; it is not an identifier.
labels	object	String tags attached to the database, as key and value pairs; empty object when none.
status	string	Lifecycle state of the database. Table, field and row calls work only while it is active.
table_count	integer	Number of tables currently in the database, at most 50; refreshed when the schema changes.
size_bytes	integer	Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately.
created_at	string	Time the database was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp.
deleted_at	string \| null	Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore.
purge_at	string \| null	Permanent deletion deadline for deleting databases; null otherwise.

curl -X PATCH "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"walk-lib-r1-DOC-5320-notes"}'

响应示例 — HTTP 200

{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-notes",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:43.514Z",
  "deleted_at": null,
  "purge_at": null
}

删除库

DELETE /database/v1/databases/{database_id}

参数	位置	说明
database_id	path	库 ID。

返回: Database.

响应

HTTP 200

Success

application/json

名称	类型	说明
id	string	Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path.
name	string	Display name given at creation or by the last update; it is not an identifier.
labels	object	String tags attached to the database, as key and value pairs; empty object when none.
status	string	Lifecycle state of the database. Table, field and row calls work only while it is active.
table_count	integer	Number of tables currently in the database, at most 50; refreshed when the schema changes.
size_bytes	integer	Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately.
created_at	string	Time the database was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp.
deleted_at	string \| null	Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore.
purge_at	string \| null	Permanent deletion deadline for deleting databases; null otherwise.

curl -X DELETE "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-notes",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "deleting",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:51.868Z",
  "deleted_at": "2026-10-11T17:41:51.868Z",
  "purge_at": "2026-10-18T17:41:51.868Z"
}

恢复库

POST /database/v1/databases/{database_id}/restore

参数	位置	说明
database_id	path	库 ID。

返回: Database.

响应

HTTP 200

Success

application/json

名称	类型	说明
id	string	Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path.
name	string	Display name given at creation or by the last update; it is not an identifier.
labels	object	String tags attached to the database, as key and value pairs; empty object when none.
status	string	Lifecycle state of the database. Table, field and row calls work only while it is active.
table_count	integer	Number of tables currently in the database, at most 50; refreshed when the schema changes.
size_bytes	integer	Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately.
created_at	string	Time the database was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp.
deleted_at	string \| null	Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore.
purge_at	string \| null	Permanent deletion deadline for deleting databases; null otherwise.

curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/restore" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-notes",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:51.528Z",
  "deleted_at": null,
  "purge_at": null
}

清除库

POST /database/v1/databases/{database_id}/purge

参数	位置	说明
database_id	path	库 ID。

返回: object.

响应

HTTP 200

Permanently purged

application/json

名称	类型	说明
id	string	Id (db_…) of the database that was permanently purged; it no longer resolves.
object	string	Resource type of the purged object; always database.
purged	boolean	Always true: the database and all of its data were permanently removed and cannot be recovered.

curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/purge" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "id": "db_d6f0d743d5a645e8",
  "object": "database",
  "purged": true
}

Database

字段	类型	必填	说明
id	string	是	资源 ID; ^db_
name	string	是	名称
labels	object	是	标签
status	"provisioning" / "active" / "deleting" / "deleted" / "failed"	是	库状态
table_count	integer	是	表数量
size_bytes	integer	是	占用字节数
created_at	date-time	是	创建时间
updated_at	date-time	是	更新时间
deleted_at	date-time / null	是	删除时间；未删除时为 null
purge_at	date-time / null	是	—

Page

字段	类型	必填	说明
data	JSON[]	是	资源数组
next_cursor	string / null	是	下一页游标；没有后续时为 null

数据表

指南 →

基础地址与鉴权

创建表

POST /database/v1/databases/{database_id}/tables

参数	位置	说明
database_id	path	库 ID。

请求体

字段	类型	必填	说明
name	string	是	名称; ^[a-z_][a-z0-9_]{0,62}$
description	string	否	描述
fields	NewField[]	是	字段列表

返回: Table.

响应

HTTP 201

Success

application/json

名称	类型	说明
id	string	Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
name	string	Current table name, usable in the rows path; may change when the table is renamed.
description	string \| null	Free-text note about the table, or null when none was set.
fields	array<object>	Field definitions of the table, in display order. Row values are keyed by each field's name.
fields[].id	string	Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
fields[].name	string	Current field name; rows are keyed by it in requests and responses. May change when the field is renamed.
fields[].description	string \| null	Free-text note about the field, or null when none was set.
fields[].required	boolean	Whether every row must hold a non-null value for this field.
fields[].unique	boolean	Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
fields[].indexed	boolean	Whether an index is maintained for faster filters and ordering. Always false for json and link fields.
fields[].type	string	Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created.
fields[].options	object	Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required.
fields[].default	any	Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults.
schema_revision	integer	Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes.
created_at	string	Time the table was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_count	integer	Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses.

curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"tasks","fields":[{"name":"title","type":"string","required":true,"unique":true},{"name":"done","type":"boolean"}]}'

响应示例 — HTTP 201

{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": null,
  "schema_revision": 1,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:44.246Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}

列出表

GET /database/v1/databases/{database_id}/tables

参数	位置	说明
database_id	path	库 ID。

返回: Page + object.

响应

HTTP 200

Success

application/json

名称	类型	说明
data	array<object>	Every table of the database with its fields, in creation order; at most 50 items.
data[].id	string	Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
data[].name	string	Current table name, usable in the rows path; may change when the table is renamed.
data[].description	string \| null	Free-text note about the table, or null when none was set.
data[].fields	array<object>	Field definitions of the table, in display order. Row values are keyed by each field's name.
data[].schema_revision	integer	Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes.
data[].created_at	string	Time the table was created, as an RFC 3339 UTC timestamp.
data[].updated_at	string	Time of the last schema change to the table, as an RFC 3339 UTC timestamp.
data[].row_count	integer	Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses.
next_cursor	string \| null	Opaque cursor for the next page, or null when there are no more items. Databases list: pass it as cursor. Events list: pass it as after_seq (order asc) or before_seq (order desc).

curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "data": [
    {
      "id": "tbl_2b3431c772754599",
      "name": "tasks",
      "description": null,
      "schema_revision": 1,
      "created_at": "2026-10-11T17:41:44.246Z",
      "updated_at": "2026-10-11T17:41:44.246Z",
      "fields": [
        {
          "id": "fld_bc71f7c6a1a848d2",
          "name": "title",
          "type": "string",
          "description": null,
          "required": true,
          "unique": true,
          "indexed": true
        },
        {
          "id": "fld_c7879883dfe04ca0",
          "name": "done",
          "type": "boolean",
          "description": null,
          "required": false,
          "unique": false,
          "indexed": true
        }
      ]
    }
  ],
  "next_cursor": null
}

读取表

GET /database/v1/databases/{database_id}/tables/{table}

参数	位置	说明
database_id	path	库 ID。
table	path	表 ID 或名称。

返回: Table.

响应

HTTP 200

Success

application/json

名称	类型	说明
id	string	Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
name	string	Current table name, usable in the rows path; may change when the table is renamed.
description	string \| null	Free-text note about the table, or null when none was set.
fields	array<object>	Field definitions of the table, in display order. Row values are keyed by each field's name.
fields[].id	string	Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
fields[].name	string	Current field name; rows are keyed by it in requests and responses. May change when the field is renamed.
fields[].description	string \| null	Free-text note about the field, or null when none was set.
fields[].required	boolean	Whether every row must hold a non-null value for this field.
fields[].unique	boolean	Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
fields[].indexed	boolean	Whether an index is maintained for faster filters and ordering. Always false for json and link fields.
fields[].type	string	Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created.
fields[].options	object	Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required.
fields[].default	any	Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults.
schema_revision	integer	Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes.
created_at	string	Time the table was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_count	integer	Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses.

curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": null,
  "schema_revision": 1,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:44.246Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ],
  "row_count": 0
}

更新表

PATCH /database/v1/databases/{database_id}/tables/{table}

参数	位置	说明
database_id	path	库 ID。
table	path	表 ID 或名称。

请求体

字段	类型	必填	说明
name	string	否	名称
description	string / null	否	描述

返回: Table.

响应

HTTP 200

Success

application/json

名称	类型	说明
id	string	Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
name	string	Current table name, usable in the rows path; may change when the table is renamed.
description	string \| null	Free-text note about the table, or null when none was set.
fields	array<object>	Field definitions of the table, in display order. Row values are keyed by each field's name.
fields[].id	string	Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
fields[].name	string	Current field name; rows are keyed by it in requests and responses. May change when the field is renamed.
fields[].description	string \| null	Free-text note about the field, or null when none was set.
fields[].required	boolean	Whether every row must hold a non-null value for this field.
fields[].unique	boolean	Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
fields[].indexed	boolean	Whether an index is maintained for faster filters and ordering. Always false for json and link fields.
fields[].type	string	Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created.
fields[].options	object	Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required.
fields[].default	any	Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults.
schema_revision	integer	Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes.
created_at	string	Time the table was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_count	integer	Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses.

curl -X PATCH "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Tasks for an agent"}'

响应示例 — HTTP 200

{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": "Tasks for an agent",
  "schema_revision": 2,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:45.127Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}

删除表

DELETE /database/v1/databases/{database_id}/tables/{table}

参数	位置	说明
database_id	path	库 ID。
table	path	表 ID 或名称。

返回: object.

响应

HTTP 200

Success

application/json

名称	类型	说明
deleted	boolean	Always true: the table and all of its rows were dropped immediately and cannot be recovered.

curl -X DELETE "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "deleted": true
}

Table

字段	类型	必填	说明
id	string	是	资源 ID; ^tbl_
name	string	是	名称
description	string / null	是	描述
fields	Field[]	是	字段列表
schema_revision	integer	是	表结构版本
created_at	date-time	是	创建时间
updated_at	date-time	是	更新时间
row_count	integer	否	行数；仅单表查询返回

Field · Page

字段

指南 →

基础地址与鉴权

添加、更新和删除字段均返回完整 Table。字段 type 不可修改；link 的关联目标不可修改。json 的 schema 更新仅约束之后的写入。

新增带 default 的字段时，已有行一律用 default 回填（无论是否 required），行的 _version 不变；不带 default 的新字段在已有行上为 null。在已有行的表上新增 required 字段时必须提供 default，没有 default 时返回 400 VALIDATION_FAILED。把字段改为 required 时，若仍有行在该字段为空，返回 400 VALIDATION_FAILED 并在 message 中给出空行数。空请求体、只含被忽略键或所有值都与当前相同的 PATCH 不修改 updated_at 与 schema_revision、不产生事件，直接返回当前对象。

datetime 的 default 可以是字符串 "now()"，插入时生成服务器当前 UTC 时间；读回字段定义仍是 "now()"。例如 {"name":"created_at","type":"datetime","default":"now()"}。string/json 的 "now()" 保持字面量；其他类型仍按原校验规则处理。新增字段回填已有行时也会求值。

添加字段

POST /database/v1/databases/{database_id}/tables/{table}/fields

参数	位置	说明
database_id	path	库 ID。
table	path	表 ID 或名称。

请求体

"string" / "integer" / "number" / "boolean" / "datetime"

字段	类型	必填	说明
name	string	是	字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	否	描述
required	boolean	否	是否必填
unique	boolean	否	是否唯一
indexed	boolean	否	是否索引
type	"string" / "integer" / "number" / "boolean" / "datetime"	是	类型
options	object	否	json：schema；link：linked_table_id 与 multiple
default	JSON	否	省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。

"json"

字段	类型	必填	说明
name	string	是	字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	否	描述
required	boolean	否	是否必填
unique	boolean	否	是否唯一
indexed	boolean	否	是否索引
type	"json"	是	类型
options	object	是	json：schema；link：linked_table_id 与 multiple
default	JSON	否	省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。

"link"

字段	类型	必填	说明
name	string	是	字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	否	描述
required	boolean	否	是否必填
unique	boolean	否	是否唯一
indexed	boolean	否	是否索引
type	"link"	是	类型
options	object	是	json：schema；link：linked_table_id 与 multiple

返回: Table.

响应

HTTP 201

Success

application/json

名称	类型	说明
id	string	Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
name	string	Current table name, usable in the rows path; may change when the table is renamed.
description	string \| null	Free-text note about the table, or null when none was set.
fields	array<object>	Field definitions of the table, in display order. Row values are keyed by each field's name.
fields[].id	string	Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
fields[].name	string	Current field name; rows are keyed by it in requests and responses. May change when the field is renamed.
fields[].description	string \| null	Free-text note about the field, or null when none was set.
fields[].required	boolean	Whether every row must hold a non-null value for this field.
fields[].unique	boolean	Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
fields[].indexed	boolean	Whether an index is maintained for faster filters and ordering. Always false for json and link fields.
fields[].type	string	Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created.
fields[].options	object	Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required.
fields[].default	any	Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults.
schema_revision	integer	Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes.
created_at	string	Time the table was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_count	integer	Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses.

curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks/fields" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"priority","type":"integer"}'

响应示例 — HTTP 201

{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": "Tasks for an agent",
  "schema_revision": 3,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:45.420Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    },
    {
      "id": "fld_4c3e63869e35458c",
      "name": "priority",
      "type": "integer",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}

更新字段

PATCH /database/v1/databases/{database_id}/tables/{table}/fields/{field}

参数	位置	说明
database_id	path	库 ID。
table	path	表 ID 或名称。
field	path	字段 ID 或名称。

请求体

字段	类型	必填	说明
name	string	否	名称
description	string / null	否	描述
required	boolean	否	是否必填
indexed	boolean	否	是否索引
options	object	否	json：schema；link：linked_table_id 与 multiple
default	JSON	否	省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。

返回: Table.

响应

HTTP 200

Success

application/json

名称	类型	说明
id	string	Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
name	string	Current table name, usable in the rows path; may change when the table is renamed.
description	string \| null	Free-text note about the table, or null when none was set.
fields	array<object>	Field definitions of the table, in display order. Row values are keyed by each field's name.
fields[].id	string	Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
fields[].name	string	Current field name; rows are keyed by it in requests and responses. May change when the field is renamed.
fields[].description	string \| null	Free-text note about the field, or null when none was set.
fields[].required	boolean	Whether every row must hold a non-null value for this field.
fields[].unique	boolean	Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
fields[].indexed	boolean	Whether an index is maintained for faster filters and ordering. Always false for json and link fields.
fields[].type	string	Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created.
fields[].options	object	Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required.
fields[].default	any	Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults.
schema_revision	integer	Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes.
created_at	string	Time the table was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_count	integer	Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses.

curl -X PATCH "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks/fields/priority" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Task priority"}'

响应示例 — HTTP 200

{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": "Tasks for an agent",
  "schema_revision": 4,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:46.276Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    },
    {
      "id": "fld_4c3e63869e35458c",
      "name": "priority",
      "type": "integer",
      "description": "Task priority",
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}

删除字段

DELETE /database/v1/databases/{database_id}/tables/{table}/fields/{field}

参数	位置	说明
database_id	path	库 ID。
table	path	表 ID 或名称。
field	path	字段 ID 或名称。

返回: Table.

响应

HTTP 200

Success

application/json

名称	类型	说明
id	string	Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
name	string	Current table name, usable in the rows path; may change when the table is renamed.
description	string \| null	Free-text note about the table, or null when none was set.
fields	array<object>	Field definitions of the table, in display order. Row values are keyed by each field's name.
fields[].id	string	Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
fields[].name	string	Current field name; rows are keyed by it in requests and responses. May change when the field is renamed.
fields[].description	string \| null	Free-text note about the field, or null when none was set.
fields[].required	boolean	Whether every row must hold a non-null value for this field.
fields[].unique	boolean	Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
fields[].indexed	boolean	Whether an index is maintained for faster filters and ordering. Always false for json and link fields.
fields[].type	string	Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created.
fields[].options	object	Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required.
fields[].default	any	Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults.
schema_revision	integer	Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes.
created_at	string	Time the table was created, as an RFC 3339 UTC timestamp.
updated_at	string	Time of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_count	integer	Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses.

curl -X DELETE "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks/fields/priority" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": "Tasks for an agent",
  "schema_revision": 5,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:47.136Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}

Field

"string" / "integer" / "number" / "boolean" / "datetime"

字段	类型	必填	说明
id	string	是	资源 ID
name	string	是	名称
description	string / null	是	描述
required	boolean	是	是否必填
unique	boolean	是	是否唯一
indexed	boolean	是	是否索引
type	"string" / "integer" / "number" / "boolean" / "datetime"	是	类型
options	object	否	json：schema；link：linked_table_id 与 multiple
default	JSON	否	省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。

"json"

字段	类型	必填	说明
id	string	是	资源 ID
name	string	是	名称
description	string / null	是	描述
required	boolean	是	是否必填
unique	boolean	是	是否唯一
indexed	boolean	是	是否索引
type	"json"	是	类型
options	object	是	json：schema；link：linked_table_id 与 multiple
default	JSON	否	省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。

"link"

字段	类型	必填	说明
id	string	是	资源 ID
name	string	是	名称
description	string / null	是	描述
required	boolean	是	是否必填
unique	boolean	是	是否唯一
indexed	boolean	是	是否索引
type	"link"	是	类型
options	object	是	json：schema；link：linked_table_id 与 multiple

NewField

"string" / "integer" / "number" / "boolean" / "datetime"

字段	类型	必填	说明
name	string	是	字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	否	描述
required	boolean	否	是否必填
unique	boolean	否	是否唯一
indexed	boolean	否	是否索引
type	"string" / "integer" / "number" / "boolean" / "datetime"	是	类型
options	object	否	json：schema；link：linked_table_id 与 multiple
default	JSON	否	省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。

"json"

字段	类型	必填	说明
name	string	是	字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	否	描述
required	boolean	否	是否必填
unique	boolean	否	是否唯一
indexed	boolean	否	是否索引
type	"json"	是	类型
options	object	是	json：schema；link：linked_table_id 与 multiple
default	JSON	否	省略插入值时的默认值；datetime 的 now() 在写入时取服务器时间，字段定义仍读回 now()。string/json 中为字面量。显式 null 不使用默认值。

"link"

字段	类型	必填	说明
name	string	是	字段名；只保留 id；新字段不能以下划线开头。created_at、updated_at、version 可作为用户字段名；已有下划线字段照常使用，且优先于同名元数据。; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	否	描述
required	boolean	否	是否必填
unique	boolean	否	是否唯一
indexed	boolean	否	是否索引
type	"link"	是	类型
options	object	是	json：schema；link：linked_table_id 与 multiple

事件

指南 →

基础地址与鉴权

事件记录库生命周期与表、字段结构变化，不记录行读写。

默认按 seq 升序；只给 before_seq 时默认按 desc（最新在前）。next_cursor 是不透明的字符串游标，原样传回：asc 时传给 after_seq，desc 时传给 before_seq。两个游标同时提供，或 before_seq 与 order=asc 同时提供，返回 400 INVALID_PARAMS。删除中的库仍可读取事件。

next_cursor 是不透明的字符串游标，原样传回，不要对它做运算；为 null 表示没有后续页。下方响应为省略 order 的升序实测结果。倒序翻页按以下请求使用；该扩展的线上响应将在服务更新后补充。

# 最新一页
curl "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/events?order=desc&limit=10" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

# 把 NEXT_CURSOR 设为上一页返回的 next_cursor
curl "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/events?order=desc&before_seq=${NEXT_CURSOR}&limit=10" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

读取事件

GET /database/v1/databases/{database_id}/events

参数	位置	说明
database_id	path	库 ID。
after_seq	query	order=asc 时，只取 seq 大于该值的事件；不可同时提供 before_seq。
limit	query	最多返回的条数。 (default: 50) (1–200)
order	query	asc 按 seq 升序，desc 为最新在前。默认 asc；只给 before_seq 时默认 desc。
before_seq	query	只取 seq 小于该值的事件，最新在前；省略 order 时按 desc。不可同时提供 after_seq 或 order=asc。

返回: Page + object.

响应

HTTP 200

Success

application/json

名称	类型	说明
data	array<object>	Events on this page in the requested order (ascending seq by default, newest first with before_seq or order=desc).
data[].seq	integer	Position of the event in the database's event log; starts at 1 and strictly increases. Use it as after_seq or before_seq to page.
data[].id	string	Unique identifier of this event record.
data[].type	string	What happened: a lifecycle transition of the database, or a schema change to a table or field.
data[].processed_at	string	Time the event was recorded, as an RFC 3339 UTC timestamp.
data[].database_id	string	Id (db_…) of the database the event belongs to.
data[].table_id	string	Id (tbl_…) of the affected table; present only for table and field events.
data[].field_id	string	Id (fld_…) of the affected field; present only for field events.
next_cursor	string \| null	Opaque cursor for the next page, or null when there are no more items. Databases list: pass it as cursor. Events list: pass it as after_seq (order asc) or before_seq (order desc).

curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/events?after_seq=0&limit=10" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应示例 — HTTP 200

{
  "data": [
    {
      "seq": 1,
      "id": "7390d75e-216c-4799-891e-c043bac8bce5",
      "type": "database.status_provisioning",
      "processed_at": "2026-10-11T17:41:41.339Z",
      "database_id": "db_d6f0d743d5a645e8"
    },
    {
      "seq": 2,
      "id": "39db0ef4-99b4-4846-9d50-9998e25cf48f",
      "type": "database.status_active",
      "processed_at": "2026-10-11T17:41:41.339Z",
      "database_id": "db_d6f0d743d5a645e8"
    },
    {
      "seq": 3,
      "id": "d295651d-5e83-4b42-bcd3-c979fb71f375",
      "type": "table.created",
      "processed_at": "2026-10-11T17:41:44.246Z",
      "database_id": "db_d6f0d743d5a645e8",
      "table_id": "tbl_2b3431c772754599"
    },
    {
      "seq": 4,
      "id": "eb255753-3dd7-4eae-8861-d53408bfcaf4",
      "type": "table.updated",
      "processed_at": "2026-10-11T17:41:45.127Z",
      "database_id": "db_d6f0d743d5a645e8",
      "table_id": "tbl_2b3431c772754599"
    },
    {
      "seq": 5,
      "id": "99c86e22-0629-4391-85e5-d7b8b31de833",
      "type": "field.added",
      "processed_at": "2026-10-11T17:41:45.420Z",
      "database_id": "db_d6f0d743d5a645e8",
      "table_id": "tbl_2b3431c772754599",
      "field_id": "fld_4c3e63869e35458c"
    },
    {
      "seq": 6,
      "id": "a9b85950-363d-4ab3-8c85-6228eec3d099",
      "type": "field.updated",
      "processed_at": "2026-10-11T17:41:46.276Z",
      "database_id": "db_d6f0d743d5a645e8",
      "table_id": "tbl_2b3431c772754599",
      "field_id": "fld_4c3e63869e35458c"
    },
    {
      "seq": 7,
      "id": "73ca124f-6cbb-4a43-8a37-4ff50a211dd5",
      "type": "field.deleted",
      "processed_at": "2026-10-11T17:41:47.136Z",
      "database_id": "db_d6f0d743d5a645e8",
      "table_id": "tbl_2b3431c772754599",
      "field_id": "fld_4c3e63869e35458c"
    }
  ],
  "next_cursor": null
}

DatabaseEvent

字段	类型	必填	说明
seq	integer	是	库内递增序号
id	string	是	资源 ID
type	"database.status_provisioning" / "database.status_active" / "database.status_deleting" / "database.status_deleted" / "database.status_failed" / "database.restored" / "table.created" / "table.updated" / "table.deleted" / "field.added" / "field.updated" / "field.deleted"	是	类型
processed_at	date-time	是	事件时间
database_id	string	是	库 ID
table_id	string	否	相关表 ID（可选）
field_id	string	否	相关字段 ID（可选）

读写行

指南 →

/database/v1/databases/{database_id}/rest/{table}

与同一库的其它入口读写相同的行；错误使用 PostgREST code。

支持矩阵与初始化

完整参数、响应头与返回状态

一次批量 POST 最多插入 500 行，单次请求是原子的：任何一行失败，整批回滚。跨请求没有事务；需要一起成功的行应放在一次批量 POST 中。有关联依赖时先查后插，并处理并发变化导致的关联错误。

同一批次按所有行的键的并集补齐缺失值为 null（PostgREST 行为）。发送 Prefer: missing=default 可改用字段默认值；显式 null 仍为 null，没有默认值的必填字段仍必须提供。默认 return=minimal 返回 201、body 为空；发送 Prefer: return=representation 才返回行。

查询行

GET /database/v1/databases/{database_id}/rest/{table}

curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?select=*&order=title.asc&limit=10" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应

HTTP 200

Success; write bodies require Prefer: return=representation

application/json

名称	类型	说明
[].id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

application/vnd.pgrst.object+json

名称	类型	说明
id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

HTTP 206

Partial range with requested count

application/json

名称	类型	说明
[].id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

application/vnd.pgrst.object+json

名称	类型	说明
id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

响应示例 — HTTP 200

响应头	值
content-range	0-0/*
etag	W/"5.1"
range-unit	items

[
  {
    "id": "rec_3e85a292099340e3",
    "version": 1,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:47.896Z",
    "title": "Write a summary",
    "done": false
  }
]

统计行

HEAD /database/v1/databases/{database_id}/rest/{table}

curl --head "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?select=*" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: count=exact'

响应

HTTP 200

Success; write bodies require Prefer: return=representation

未声明响应体。

HTTP 206

Partial range with requested count

未声明响应体。

响应示例 — HTTP 200

响应头	值
content-range	0-0/1
preference-applied	count=exact
etag	W/"5.1"
range-unit	items

无响应正文。

插入行

POST /database/v1/databases/{database_id}/rest/{table}

curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: return=representation' \
  -H "Content-Type: application/json" \
  -d '{"title":"Write a summary","done":false}'

响应

HTTP 201

Success (201). With the default return=minimal the body is empty; Prefer: return=representation returns rows.

application/json

名称	类型	说明
[].id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

application/vnd.pgrst.object+json

名称	类型	说明
id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

响应示例 — HTTP 201

响应头	值
content-range	0-0/*
preference-applied	return=representation
range-unit	items

[
  {
    "id": "rec_3e85a292099340e3",
    "version": 1,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:47.896Z",
    "title": "Write a summary",
    "done": false
  }
]

更新行

PATCH /database/v1/databases/{database_id}/rest/{table}

curl -X PATCH "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?title=eq.Write%20a%20summary" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: return=representation' \
  -H "Content-Type: application/json" \
  -d '{"done":true}'

响应

HTTP 200

Success; write bodies require Prefer: return=representation

application/json

名称	类型	说明
[].id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

application/vnd.pgrst.object+json

名称	类型	说明
id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

HTTP 204

Success without a body

未声明响应体。

响应示例 — HTTP 200

响应头	值
content-range	0-0/*
preference-applied	return=representation
range-unit	items

[
  {
    "id": "rec_3e85a292099340e3",
    "version": 2,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:48.802Z",
    "title": "Write a summary",
    "done": true
  }
]

合并行

POST /database/v1/databases/{database_id}/rest/{table}

curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?on_conflict=title" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: resolution=merge-duplicates,return=representation' \
  -H "Content-Type: application/json" \
  -d '{"title":"Write a summary","done":true}'

响应

HTTP 201

Success (201). With the default return=minimal the body is empty; Prefer: return=representation returns rows.

application/json

名称	类型	说明
[].id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

application/vnd.pgrst.object+json

名称	类型	说明
id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

响应示例 — HTTP 201

响应头	值
content-range	0-0/*
preference-applied	resolution=merge-duplicates, return=representation
range-unit	items

[
  {
    "id": "rec_3e85a292099340e3",
    "version": 3,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:49.076Z",
    "title": "Write a summary",
    "done": true
  }
]

删除行

DELETE /database/v1/databases/{database_id}/rest/{table}

curl -X DELETE "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?title=eq.Write%20a%20summary" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: return=representation'

响应

HTTP 200

Success; write bodies require Prefer: return=representation

application/json

名称	类型	说明
[].id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

application/vnd.pgrst.object+json

名称	类型	说明
id	string	Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates.

HTTP 204

Success without a body

未声明响应体。

响应示例 — HTTP 200

响应头	值
content-range	0-0/*
preference-applied	return=representation
range-unit	items

[
  {
    "id": "rec_3e85a292099340e3",
    "version": 3,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:49.076Z",
    "title": "Write a summary",
    "done": true
  }
]

Row

默认投影、select=、return=representation 与 RPC 行对象只返回 id 和用户字段。系统元数据须显式点名，例如 select=,_version,_created_at,_updated_at；* 不展开它们。可用 _version=eq.3 过滤、order=_created_at.desc 排序，但不可写。未指定 order 时仍按内部创建时间、id 排序。没有同名用户字段时，旧名 created_at/updated_at/version 用于过滤或排序返回 400，details 为 use _created_at（或对应名字），hint 为 system metadata moved to underscore columns。已有下划线用户字段优先，同名系统元数据在该表上不可访问。上方历史响应样例采集于此规则调整前，仍可能包含旧元数据列；当前行形状以本节为准。

字段	类型	必填	说明
id	string	是	资源 ID; ^[A-Za-z0-9_-]{1,64}$

错误码

管理端点返回领域码；两个表端点返回 PostgREST code。HTTP 状态与重试属性如下。

领域码	HTTP	PostgREST code	可重试
SINGULAR_MISMATCH	406	PGRST116	否
AMBIGUOUS_EMBED	300	PGRST201	否
EMBED_NOT_FOUND	400	PGRST200	否
INVALID_PREFERENCE	400	PGRST122	否
QUERY_CANCELED	500	57014	否
RANGE_NOT_SATISFIABLE	416	PGRST103	否
NOT_ACCEPTABLE	406	PGRST107	否
OPERATOR_TYPE_MISMATCH	400	42883	否
DATABASE_NOT_FOUND	404	PGRST125	否
TABLE_NOT_FOUND	404	PGRST205	否
FIELD_NOT_FOUND	400	42703	否
VALIDATION_FAILED	400	23514	否
UNIQUE_VIOLATION	409	23505	否
REFERENCE_RESTRICT	409	23503	否
FIELD_TYPE_IMMUTABLE	400	—	否
LIMIT_EXCEEDED	400	54000	否
UNSUPPORTED	400	PGRST127	否
INVALID_PARAMS	400	PGRST100	否
DATABASE_INVALID_STATE	409	—	否
CAPACITY	503	—	是
NOT_IMPLEMENTED	501	PGRST127	否

可重试不表示重复原请求一定成功。例如 57014 应先缩小查询范围或调整过滤条件，再重试。

管理端点错误体

响应示例 — HTTP 400

{
  "code": "FIELD_TYPE_IMMUTABLE",
  "message": "field type is immutable",
  "details": null,
  "hint": null
}

表端点错误体

响应示例 — HTTP 400

{
  "code": "PGRST127",
  "message": "operator fts is not supported",
  "details": null,
  "hint": null
}

code、message、details、hint 四个字段始终存在；details 与 hint 可以为 null。

未开放服务错误体

响应示例 — HTTP 501

响应头	值
x-should-retry	false

{
  "code": "not_implemented",
  "message": "auth is not provided by praxis-database"
}

这五个服务直接返回 not_implemented；它与错误表中的领域码 NOT_IMPLEMENTED 不同。

按错误细节修正请求

保留字段名只有 id；新字段名不能以 _ 开头，这个前缀留给系统元数据。created_at、updated_at、version 可用作普通字段名。datetime 字段可用 "now()" 作为默认值。

details 指出字段或 JSON 路径及实际收到的值，批量校验还包含从 0 开始的行号。值最多显示 80 个字符，不回显整行。hint 给出修正方式，没有建议时为 null。下面是省略第 2 行必填 title 的错误示例：

{
  "code": "23514",
  "message": "row validation failed",
  "details": "row 1: title: required value (got null)",
  "hint": "Rows in one insert are filled to the union of their keys with null (PostgREST behavior). Send every key in every row, or send Prefer: missing=default to use field defaults."
}

唯一冲突返回 409，例如：

{
  "code": "23505",
  "message": "unique constraint violated",
  "details": "Key (email)=(a@b.c) already exists.",
  "hint": null
}