Fields

Adding, updating or deleting a field returns the complete Table. Field types and link targets are immutable. JSON Schema updates apply to subsequent writes.

A new field with a default fills every existing row with it, required or not, without changing row versions; a new field without a default is null on existing rows. Adding a required field to a table that already has rows needs a default; without one the request returns 400 VALIDATION_FAILED. Making a field required while some rows are null in it returns 400 VALIDATION_FAILED, with the number of null rows in the message. A PATCH with an empty body, only ignored keys, or only values equal to the current ones changes neither updated_at nor schema_revision, records no event and returns the current object.

A datetime default can be the string "now()": insertion evaluates it to current server UTC time, while the field definition still returns "now()". Example: {"name":"created_at","type":"datetime","default":"now()"}. String/json fields keep the literal; other types retain normal validation. Adding a field also evaluates this default when backfilling existing rows.

Add field

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

Parameter	Location	Description
database_id	path	Identifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted.
table	path	table ID or name.

Request body

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

Field	Type	Required	Description
name	string	yes	Field name. Only id is reserved; new field names cannot start with _ (reserved for system metadata). created_at, updated_at and version are ordinary user field names. Existing underscore-prefixed fields remain usable and take precedence over metadata.; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	no	Optional free-text note about the field; omit it to store null.
required	boolean	no	Whether every row must hold a non-null value for this field. Defaults to false.
unique	boolean	no	Whether values must be distinct across rows. Defaults to false; cannot be changed after the field exists. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
indexed	boolean	no	Whether to maintain an index for faster filters and ordering. Defaults to true for scalar types and is not allowed for json and link fields. At most 16 indexed or unique fields per table.
type	"string" / "integer" / "number" / "boolean" / "datetime"	yes	Scalar data type of the field; it cannot be changed after the field is created.
options	object	no	Scalar fields take no options; always an empty object.
default	JSON	no	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.

"json"

Field	Type	Required	Description
name	string	yes	Field name. Only id is reserved; new field names cannot start with _ (reserved for system metadata). created_at, updated_at and version are ordinary user field names. Existing underscore-prefixed fields remain usable and take precedence over metadata.; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	no	Optional free-text note about the field; omit it to store null.
required	boolean	no	Whether every row must hold a non-null value for this field. Defaults to false.
unique	boolean	no	Whether values must be distinct across rows. Defaults to false; cannot be changed after the field exists. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
indexed	boolean	no	Whether to maintain an index for faster filters and ordering. Defaults to true for scalar types and is not allowed for json and link fields. At most 16 indexed or unique fields per table.
type	"json"	yes	Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created.
options	object	yes	Settings of a json field. schema is required.
default	JSON	no	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.

"link"

Field	Type	Required	Description
name	string	yes	Field name. Only id is reserved; new field names cannot start with _ (reserved for system metadata). created_at, updated_at and version are ordinary user field names. Existing underscore-prefixed fields remain usable and take precedence over metadata.; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	no	Optional free-text note about the field; omit it to store null.
required	boolean	no	Whether every row must hold a non-null value for this field. Defaults to false.
unique	boolean	no	Whether values must be distinct across rows. Defaults to false; cannot be changed after the field exists. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
indexed	boolean	no	Whether to maintain an index for faster filters and ordering. Defaults to true for scalar types and is not allowed for json and link fields. At most 16 indexed or unique fields per table.
type	"link"	yes	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.
options	object	yes	Settings of a link field. Both linked_table_id and multiple are required.

Returns: Table.

Response

HTTP 201

Success

application/json

Name	Type	Description
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"}'

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

Update field

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

Parameter	Location	Description
database_id	path	Identifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted.
table	path	table ID or name.
field	path	field ID or name.

Request body

Field	Type	Required	Description
name	string	no	New field name (lowercase letters, digits and underscores; id and names starting with _ are reserved). Renaming does not rewrite stored rows. Omit it to keep the current name.
description	string / null	no	New description text, or null to clear it. Omit it to keep the current description.
required	boolean	no	Whether every row must hold a non-null value for this field. Setting true fails with 400 VALIDATION_FAILED while existing rows have null for the field; fill them first.
indexed	boolean	no	Whether to maintain an index on this field to speed up filters and ordering. Only scalar fields (string, integer, number, boolean, datetime) can be indexed; true on json or link fields is rejected, and a table allows at most 16 indexed or unique fields.
options	object	no	Type-specific settings. Only json fields accept changes, through options.schema; scalar fields take no options, and a link field's options cannot change.
default	JSON	no	Sets the default for future inserts. Must match the current type and JSON schema; not supported for link fields.

Returns: Table.

Response

HTTP 200

Success

application/json

Name	Type	Description
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"}'

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

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

Parameter	Location	Description
database_id	path	Identifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted.
table	path	table ID or name.
field	path	field ID or name.

Returns: Table.

Response

HTTP 200

Success

application/json

Name	Type	Description
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"

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

Field	Type	Required	Description
id	string	yes	Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
name	string	yes	Current field name; rows are keyed by it in requests and responses. May change when the field is renamed.
description	string / null	yes	Free-text note about the field, or null when none was set.
required	boolean	yes	Whether every row must hold a non-null value for this field.
unique	boolean	yes	Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
indexed	boolean	yes	Whether an index is maintained for faster filters and ordering. Always false for json and link fields.
type	"string" / "integer" / "number" / "boolean" / "datetime"	yes	Scalar data type of the field; it cannot be changed after the field is created.
options	object	no	Scalar fields take no options; always an empty object.
default	JSON	no	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.

"json"

Field	Type	Required	Description
id	string	yes	Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
name	string	yes	Current field name; rows are keyed by it in requests and responses. May change when the field is renamed.
description	string / null	yes	Free-text note about the field, or null when none was set.
required	boolean	yes	Whether every row must hold a non-null value for this field.
unique	boolean	yes	Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
indexed	boolean	yes	Whether an index is maintained for faster filters and ordering. Always false for json and link fields.
type	"json"	yes	Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created.
options	object	yes	Settings of a json field. schema is required.
default	JSON	no	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.

"link"

Field	Type	Required	Description
id	string	yes	Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name.
name	string	yes	Current field name; rows are keyed by it in requests and responses. May change when the field is renamed.
description	string / null	yes	Free-text note about the field, or null when none was set.
required	boolean	yes	Whether every row must hold a non-null value for this field.
unique	boolean	yes	Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
indexed	boolean	yes	Whether an index is maintained for faster filters and ordering. Always false for json and link fields.
type	"link"	yes	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.
options	object	yes	Settings of a link field. Both linked_table_id and multiple are required.

NewField

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

Field	Type	Required	Description
name	string	yes	Field name. Only id is reserved; new field names cannot start with _ (reserved for system metadata). created_at, updated_at and version are ordinary user field names. Existing underscore-prefixed fields remain usable and take precedence over metadata.; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	no	Optional free-text note about the field; omit it to store null.
required	boolean	no	Whether every row must hold a non-null value for this field. Defaults to false.
unique	boolean	no	Whether values must be distinct across rows. Defaults to false; cannot be changed after the field exists. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
indexed	boolean	no	Whether to maintain an index for faster filters and ordering. Defaults to true for scalar types and is not allowed for json and link fields. At most 16 indexed or unique fields per table.
type	"string" / "integer" / "number" / "boolean" / "datetime"	yes	Scalar data type of the field; it cannot be changed after the field is created.
options	object	no	Scalar fields take no options; always an empty object.
default	JSON	no	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.

"json"

Field	Type	Required	Description
name	string	yes	Field name. Only id is reserved; new field names cannot start with _ (reserved for system metadata). created_at, updated_at and version are ordinary user field names. Existing underscore-prefixed fields remain usable and take precedence over metadata.; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	no	Optional free-text note about the field; omit it to store null.
required	boolean	no	Whether every row must hold a non-null value for this field. Defaults to false.
unique	boolean	no	Whether values must be distinct across rows. Defaults to false; cannot be changed after the field exists. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
indexed	boolean	no	Whether to maintain an index for faster filters and ordering. Defaults to true for scalar types and is not allowed for json and link fields. At most 16 indexed or unique fields per table.
type	"json"	yes	Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created.
options	object	yes	Settings of a json field. schema is required.
default	JSON	no	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.

"link"

Field	Type	Required	Description
name	string	yes	Field name. Only id is reserved; new field names cannot start with _ (reserved for system metadata). created_at, updated_at and version are ordinary user field names. Existing underscore-prefixed fields remain usable and take precedence over metadata.; ^(?!id$)[a-z][a-z0-9_]{0,62}$
description	string	no	Optional free-text note about the field; omit it to store null.
required	boolean	no	Whether every row must hold a non-null value for this field. Defaults to false.
unique	boolean	no	Whether values must be distinct across rows. Defaults to false; cannot be changed after the field exists. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION.
indexed	boolean	no	Whether to maintain an index for faster filters and ordering. Defaults to true for scalar types and is not allowed for json and link fields. At most 16 indexed or unique fields per table.
type	"link"	yes	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.
options	object	yes	Settings of a link field. Both linked_table_id and multiple are required.

Fields

On this page