PraxisDocs
Console
Database

Tables

Requests, objects and response examples.

Guide →

Base URL and authentication

Create table

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

ParameterLocationDescription
database_idpathIdentifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted.

Request body

FieldTypeRequiredDescription
namestringyesTable name used in the rows path and in link references. Must match ^[a-z_][a-z0-9_]{0,62}$ and be unused in this database; it can be renamed later without affecting data.; ^[a-z_][a-z0-9_]{0,62}$
descriptionstringnoOptional free-text note describing what the table stores. Returned as description on the table; omit it to store null.
fieldsNewField[]yesInitial field definitions, in display order; may be an empty array. At most 64 fields per table and at most 16 indexed or unique fields. Each item follows the NewField shape selected by its type.

Returns: Table.

Response

HTTP 201

Success

application/json

NameTypeDescription
idstringTable identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
namestringCurrent table name, usable in the rows path; may change when the table is renamed.
descriptionstring | nullFree-text note about the table, or null when none was set.
fieldsarray<object>Field definitions of the table, in display order. Row values are keyed by each field's name.
fields[].idstringField identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
fields[].namestringCurrent field name; rows are keyed by it in requests and responses. May change when the field is renamed.
fields[].descriptionstring | nullFree-text note about the field, or null when none was set.
fields[].requiredbooleanWhether every row must hold a non-null value for this field.
fields[].uniquebooleanWhether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
fields[].indexedbooleanWhether an index is maintained for faster filters and ordering. Always false for json and link fields.
fields[].typestringScalar 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[].optionsobjectScalar 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[].defaultanyDefault 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_revisionintegerCounter 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_atstringTime the table was created, as an RFC 3339 UTC timestamp.
updated_atstringTime of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_countintegerNumber 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"}]}'

Response example — 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
    }
  ]
}

List tables

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

ParameterLocationDescription
database_idpathIdentifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted.

Returns: Page + object.

Response

HTTP 200

Success

application/json

NameTypeDescription
dataarray<object>Every table of the database with its fields, in creation order; at most 50 items.
data[].idstringTable identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
data[].namestringCurrent table name, usable in the rows path; may change when the table is renamed.
data[].descriptionstring | nullFree-text note about the table, or null when none was set.
data[].fieldsarray<object>Field definitions of the table, in display order. Row values are keyed by each field's name.
data[].schema_revisionintegerCounter 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_atstringTime the table was created, as an RFC 3339 UTC timestamp.
data[].updated_atstringTime of the last schema change to the table, as an RFC 3339 UTC timestamp.
data[].row_countintegerNumber of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses.
next_cursorstring | nullOpaque 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"

Response example — 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 table

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

ParameterLocationDescription
database_idpathIdentifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted.
tablepathtable ID or name.

Returns: Table.

Response

HTTP 200

Success

application/json

NameTypeDescription
idstringTable identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
namestringCurrent table name, usable in the rows path; may change when the table is renamed.
descriptionstring | nullFree-text note about the table, or null when none was set.
fieldsarray<object>Field definitions of the table, in display order. Row values are keyed by each field's name.
fields[].idstringField identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
fields[].namestringCurrent field name; rows are keyed by it in requests and responses. May change when the field is renamed.
fields[].descriptionstring | nullFree-text note about the field, or null when none was set.
fields[].requiredbooleanWhether every row must hold a non-null value for this field.
fields[].uniquebooleanWhether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
fields[].indexedbooleanWhether an index is maintained for faster filters and ordering. Always false for json and link fields.
fields[].typestringScalar 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[].optionsobjectScalar 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[].defaultanyDefault 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_revisionintegerCounter 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_atstringTime the table was created, as an RFC 3339 UTC timestamp.
updated_atstringTime of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_countintegerNumber 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"

Response example — 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
}

Update table

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

ParameterLocationDescription
database_idpathIdentifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted.
tablepathtable ID or name.

Request body

FieldTypeRequiredDescription
namestringnoNew table name matching ^[a-z_][a-z0-9_]{0,62}$ and unused in this database. Omit it to keep the current name.
descriptionstring / nullnoNew description text, or null to clear it. Omit it to keep the current description.

Returns: Table.

Response

HTTP 200

Success

application/json

NameTypeDescription
idstringTable identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.
namestringCurrent table name, usable in the rows path; may change when the table is renamed.
descriptionstring | nullFree-text note about the table, or null when none was set.
fieldsarray<object>Field definitions of the table, in display order. Row values are keyed by each field's name.
fields[].idstringField identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
fields[].namestringCurrent field name; rows are keyed by it in requests and responses. May change when the field is renamed.
fields[].descriptionstring | nullFree-text note about the field, or null when none was set.
fields[].requiredbooleanWhether every row must hold a non-null value for this field.
fields[].uniquebooleanWhether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
fields[].indexedbooleanWhether an index is maintained for faster filters and ordering. Always false for json and link fields.
fields[].typestringScalar 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[].optionsobjectScalar 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[].defaultanyDefault 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_revisionintegerCounter 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_atstringTime the table was created, as an RFC 3339 UTC timestamp.
updated_atstringTime of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_countintegerNumber 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"}'

Response example — 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 table

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

ParameterLocationDescription
database_idpathIdentifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted.
tablepathtable ID or name.

Returns: object.

Response

HTTP 200

Success

application/json

NameTypeDescription
deletedbooleanAlways 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"

Response example — HTTP 200

{
  "deleted": true
}

Table

FieldTypeRequiredDescription
idstringyesTable identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name.; ^tbl_
namestringyesCurrent table name, usable in the rows path; may change when the table is renamed.
descriptionstring / nullyesFree-text note about the table, or null when none was set.
fieldsField[]yesField definitions of the table, in display order. Row values are keyed by each field's name.
schema_revisionintegeryesCounter 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_atdate-timeyesTime the table was created, as an RFC 3339 UTC timestamp.
updated_atdate-timeyesTime of the last schema change to the table, as an RFC 3339 UTC timestamp.
row_countintegernoNumber of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses.

Field · Page

Databases

Requests, objects and response examples.

Fields

Requests, objects and response examples.

Export
Page as MarkdownSection as MarkdownWhole book PDF

On this page

Create tableRequest bodyResponseHTTP 201List tablesResponseHTTP 200Get tableResponseHTTP 200Update tableRequest bodyResponseHTTP 200Delete tableResponseHTTP 200Table