数据表

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

数据表

创建表

请求体

响应

HTTP 201

列出表

响应

HTTP 200

读取表

响应

HTTP 200

更新表

请求体

响应

HTTP 200

删除表

响应

HTTP 200

Table

本页内容