> For the complete documentation index, see [llms.txt](https://docs.ninox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ninox.com/ninox-api/api-reference/api-endpoints/fields.md).

# Fields

## List all fields in a table

> Retrieves all fields defined in a table. Each field in the response includes type-specific properties: \`options\` (array for choice/multi, expression string for dchoice/dmulti), \`optionName\` / \`optionIcon\` / \`optionColor\` for dchoice/dmulti, and \`expression\` for function fields. Any configured \`canRead\` / \`canWrite\` permission guards are included for every type.

```json
{"openapi":"3.0.0","info":{"title":"Ninox Public API","version":"1.0.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"API Key","description":"Enter your Workspace API key. \n\n API keys can be generated and managed within the **Workspace Integration** settings in the Ninox app.","in":"header","name":"Authorization","type":"http"}},"schemas":{"FieldsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"binding":{"description":"Read-only: internal binding reference, format not yet specified","type":"string"},"canRead":{"description":"Script expression gating field-level read access","type":"string"},"canWrite":{"description":"Script expression gating field-level write access","type":"string"},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},{"type":"array","items":{"type":"string"}}]},"expression":{"description":"Expression (for function type)","type":"string"},"expressionErrors":{"description":"Expression validation errors (for function type)","type":"array","items":{"type":"object","properties":{"column":{"type":"number","description":"Column number where the error occurred"},"line":{"type":"number","description":"Line number where the error occurred"},"message":{"type":"string","description":"Error message"}},"required":["column","line","message"]}},"index":{"description":"Field is indexed","type":"boolean"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Field name"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"optionColor":{"description":"Color expression for dchoice/dmulti fields","type":"string"},"optionIcon":{"description":"Icon expression for dchoice/dmulti fields","type":"string"},"optionName":{"description":"Display name expression for dchoice/dmulti fields","type":"string"},"options":{"description":"Options array for choice/multi fields, or selection expression for dchoice/dmulti fields","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"type":"string","description":"Stable option id"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Option name"},"order":{"type":"number","description":"Option display order"},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["id","name","order"]}},{"type":"string"}]},"readRoles":{"description":"Roles allowed to read the field","type":"array","items":{"type":"string"}},"refTableId":{"description":"Reference table id","type":"string"},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"syncedFrom":{"description":"Source column this field syncs from. Read-only unless the table has two-way sync with updates enabled, in which case every synced field except the key column is writable.","type":"string"},"type":{"type":"string","enum":["any","appointment","boolean","choice","color","date","dchoice","dmulti","file","function","html","icon","lambda","multi","number","react","reference","reverse","rowId","string","styled","time","timeinterval","timestamp","unknown","user","void"],"description":"Field type"},"unique":{"description":"Field is unique","type":"boolean"},"variant":{"description":"Field variant (for string type)","type":"string"},"writeRoles":{"description":"Roles allowed to write to the field","type":"array","items":{"type":"string"}}},"required":["name","type"]},"description":"List of fields"},"page_info":{"type":"object","properties":{"has_more":{"type":"boolean","description":"Whether more results are available"},"limit":{"type":"number","description":"Maximum results per page"},"offset":{"type":"number","description":"Current offset"}},"description":"Pagination information"}},"required":["data","page_info"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/fields":{"get":{"operationId":"FieldsV1Controller_getFields","summary":"List all fields in a table","description":"Retrieves all fields defined in a table. Each field in the response includes type-specific properties: `options` (array for choice/multi, expression string for dchoice/dmulti), `optionName` / `optionIcon` / `optionColor` for dchoice/dmulti, and `expression` for function fields. Any configured `canRead` / `canWrite` permission guards are included for every type.","parameters":[{"name":"moduleName","required":true,"in":"path","description":"Module name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"tableName","required":true,"in":"path","description":"Table name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"Workspace ID","schema":{"minLength":12,"maxLength":12,"pattern":"^[a-z0-9]+$","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of fields to return","schema":{"minimum":1,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of fields to skip (starts with 0)","schema":{"minimum":0,"type":"number"}}],"responses":{"200":{"description":"Fields retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldsListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Table not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Fields"]}}}}
```

## Create a field

> Creates a new field in a table.\
> \
> \*\*Choice / multi fields:\*\* provide an \`options\` array with initial values. Each option receives a server-assigned stable \`id\` returned in the response.\
> \
> \*\*Dynamic choice / dmulti fields:\*\* \`options\` is required and must be an expression that resolves the selectable records at runtime. \`optionName\`, \`optionIcon\`, and \`optionColor\` are optional display-value expressions. All expressions are validated after save — if any are invalid the field is still created and the response includes an \`expressionErrors\` array.\
> \
> \*\*Logic (function) fields:\*\* \`expression\` is validated after save; errors are returned in \`expressionErrors\`.\
> \
> \*\*Permission guards:\*\* \`canRead\` and \`canWrite\` are Ninox Script expressions evaluated per record, so they can permit the field on one record and refuse it on the next. Unlike the expressions above they are compiled \*before\* the field is created and an expression that does not parse returns 400 — a guard that fails at evaluation time denies access, so a broken one would lock the field rather than warn. \`canWrite\` is rejected for computed and system-generated types (\`function\`, \`lambda\`, \`reverse\`, \`rowId\`, \`void\`), which have no write path to guard; \`canRead\` is accepted for every type. Both require the \`schema:manage-permissions\` grant. On create, a guard cannot reference the field being created — it is not yet in the table's script scope; set such a guard with a follow-up PATCH.\
> \
> \*\*Not creatable via this endpoint:\*\* \`any\`, \`lambda\`, \`react\`, \`rowId\`, \`styled\`, \`unknown\`, \`void\` are internal script-type artifacts with no UI presence (\`lambda\` has no storage column at all) — intentionally excluded, not a gap.

```json
{"openapi":"3.0.0","info":{"title":"Ninox Public API","version":"1.0.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"API Key","description":"Enter your Workspace API key. \n\n API keys can be generated and managed within the **Workspace Integration** settings in the Ninox app.","in":"header","name":"Authorization","type":"http"}},"schemas":{"CreateFieldBody":{"type":"object","properties":{"canRead":{"description":"Script expression that must allow reading this field's value","type":"string","minLength":1},"canWrite":{"description":"Script expression that must allow writing this field's value","type":"string","minLength":1},"expression":{"description":"Expression (for function type)","type":"string"},"labels":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":100},"description":"Field labels (localized)"},"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","description":"Field name"},"optionColor":{"description":"Color expression (for dchoice/dmulti types)","type":"string"},"optionIcon":{"description":"Icon expression (for dchoice/dmulti types)","type":"string"},"optionName":{"description":"Display name expression (for dchoice/dmulti types)","type":"string"},"options":{"description":"Options array (for choice/multi types) or selection expression (for dchoice/dmulti types)","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"description":"Stable option id (omit for new options; system assigns id)","type":"string"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","minLength":1,"description":"Option name"},"order":{"description":"Option display order","type":"integer","minimum":0,"maximum":9007199254740991},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["name"],"additionalProperties":false}},{"type":"string"}]},"refTableName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","default":null,"description":"Reference table name (for reference/reverse types)","nullable":true},"showInTable":{"description":"Show this field as a column in the table's default view (default: true)","type":"boolean"},"type":{"type":"string","enum":["string","html","number","boolean","choice","dchoice","multi","dmulti","file","date","timestamp","time","timeinterval","appointment","icon","color","user","reference","reverse","function"],"description":"Field type"},"variant":{"description":"Field variant (for string type)","type":"string","enum":["multiline-text","text","phone","email","url","location","signature"]},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"type":"array","items":{"type":"string"}},{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},"index":{"description":"Field is indexed","type":"boolean"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"readRoles":{"description":"Roles allowed to read the field (\"user\" is a deprecated alias for \"editor\")","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["admin","editor","user"]}},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"unique":{"description":"Field is unique","type":"boolean"},"writeRoles":{"description":"Roles allowed to write to the field (\"user\" is a deprecated alias for \"editor\")","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["admin","editor","user"]}}},"required":["labels","name","type"],"additionalProperties":false},"FieldResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"binding":{"description":"Read-only: internal binding reference, format not yet specified","type":"string"},"canRead":{"description":"Script expression gating field-level read access","type":"string"},"canWrite":{"description":"Script expression gating field-level write access","type":"string"},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},{"type":"array","items":{"type":"string"}}]},"expression":{"description":"Expression (for function type)","type":"string"},"expressionErrors":{"description":"Expression validation errors (for function type)","type":"array","items":{"type":"object","properties":{"column":{"type":"number","description":"Column number where the error occurred"},"line":{"type":"number","description":"Line number where the error occurred"},"message":{"type":"string","description":"Error message"}},"required":["column","line","message"]}},"index":{"description":"Field is indexed","type":"boolean"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Field name"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"optionColor":{"description":"Color expression for dchoice/dmulti fields","type":"string"},"optionIcon":{"description":"Icon expression for dchoice/dmulti fields","type":"string"},"optionName":{"description":"Display name expression for dchoice/dmulti fields","type":"string"},"options":{"description":"Options array for choice/multi fields, or selection expression for dchoice/dmulti fields","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"type":"string","description":"Stable option id"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Option name"},"order":{"type":"number","description":"Option display order"},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["id","name","order"]}},{"type":"string"}]},"readRoles":{"description":"Roles allowed to read the field","type":"array","items":{"type":"string"}},"refTableId":{"description":"Reference table id","type":"string"},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"syncedFrom":{"description":"Source column this field syncs from. Read-only unless the table has two-way sync with updates enabled, in which case every synced field except the key column is writable.","type":"string"},"type":{"type":"string","enum":["any","appointment","boolean","choice","color","date","dchoice","dmulti","file","function","html","icon","lambda","multi","number","react","reference","reverse","rowId","string","styled","time","timeinterval","timestamp","unknown","user","void"],"description":"Field type"},"unique":{"description":"Field is unique","type":"boolean"},"variant":{"description":"Field variant (for string type)","type":"string"},"writeRoles":{"description":"Roles allowed to write to the field","type":"array","items":{"type":"string"}}},"description":"Field details"}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/fields":{"post":{"operationId":"FieldsV1Controller_createField","summary":"Create a field","description":"Creates a new field in a table.\n\n**Choice / multi fields:** provide an `options` array with initial values. Each option receives a server-assigned stable `id` returned in the response.\n\n**Dynamic choice / dmulti fields:** `options` is required and must be an expression that resolves the selectable records at runtime. `optionName`, `optionIcon`, and `optionColor` are optional display-value expressions. All expressions are validated after save — if any are invalid the field is still created and the response includes an `expressionErrors` array.\n\n**Logic (function) fields:** `expression` is validated after save; errors are returned in `expressionErrors`.\n\n**Permission guards:** `canRead` and `canWrite` are Ninox Script expressions evaluated per record, so they can permit the field on one record and refuse it on the next. Unlike the expressions above they are compiled *before* the field is created and an expression that does not parse returns 400 — a guard that fails at evaluation time denies access, so a broken one would lock the field rather than warn. `canWrite` is rejected for computed and system-generated types (`function`, `lambda`, `reverse`, `rowId`, `void`), which have no write path to guard; `canRead` is accepted for every type. Both require the `schema:manage-permissions` grant. On create, a guard cannot reference the field being created — it is not yet in the table's script scope; set such a guard with a follow-up PATCH.\n\n**Not creatable via this endpoint:** `any`, `lambda`, `react`, `rowId`, `styled`, `unknown`, `void` are internal script-type artifacts with no UI presence (`lambda` has no storage column at all) — intentionally excluded, not a gap.","parameters":[{"name":"moduleName","required":true,"in":"path","description":"Module name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"tableName","required":true,"in":"path","description":"Table name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"Workspace ID","schema":{"minLength":12,"maxLength":12,"pattern":"^[a-z0-9]+$","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFieldBody"}}}},"responses":{"201":{"description":"Field created successfully. If the field contains an expression (function, dchoice, dmulti) and it has syntax errors, the response still returns 201 but includes an `expressionErrors` array.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldResponse"}}}},"400":{"description":"Bad request — validation failure (e.g., missing required fields, field already exists, invalid field type)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Workspace, module or table not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Fields"]}}}}
```

## Create multiple fields (batch)

> Creates multiple fields in a table within a single transaction. If any field creation fails, all changes are rolled back.\
> \
> The same rules as the single-create endpoint apply per field: choice/multi fields accept an initial \`options\` array; dchoice/dmulti fields require an \`options\` expression; logic fields accept an optional \`expression\`. All expressions are validated after save — invalid expressions do not prevent creation but add an \`expressionErrors\` array to the affected field in the response.\
> \
> \`canRead\` / \`canWrite\` follow the single-create rules too, with one difference in effect: they are compiled before the transaction, so one field with an uncompilable guard returns 400 and no field in the batch is created.

```json
{"openapi":"3.0.0","info":{"title":"Ninox Public API","version":"1.0.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"API Key","description":"Enter your Workspace API key. \n\n API keys can be generated and managed within the **Workspace Integration** settings in the Ninox app.","in":"header","name":"Authorization","type":"http"}},"schemas":{"CreateFieldsBatchBody":{"minItems":1,"type":"array","items":{"type":"object","properties":{"canRead":{"description":"Script expression that must allow reading this field's value","type":"string","minLength":1},"canWrite":{"description":"Script expression that must allow writing this field's value","type":"string","minLength":1},"expression":{"description":"Expression (for function type)","type":"string"},"labels":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":100},"description":"Field labels (localized)"},"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","description":"Field name"},"optionColor":{"description":"Color expression (for dchoice/dmulti types)","type":"string"},"optionIcon":{"description":"Icon expression (for dchoice/dmulti types)","type":"string"},"optionName":{"description":"Display name expression (for dchoice/dmulti types)","type":"string"},"options":{"description":"Options array (for choice/multi types) or selection expression (for dchoice/dmulti types)","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"description":"Stable option id (omit for new options; system assigns id)","type":"string"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","minLength":1,"description":"Option name"},"order":{"description":"Option display order","type":"integer","minimum":0,"maximum":9007199254740991},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["name"],"additionalProperties":false}},{"type":"string"}]},"refTableName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","default":null,"description":"Reference table name (for reference/reverse types)","nullable":true},"showInTable":{"description":"Show this field as a column in the table's default view (default: true)","type":"boolean"},"type":{"type":"string","enum":["string","html","number","boolean","choice","dchoice","multi","dmulti","file","date","timestamp","time","timeinterval","appointment","icon","color","user","reference","reverse","function"],"description":"Field type"},"variant":{"description":"Field variant (for string type)","type":"string","enum":["multiline-text","text","phone","email","url","location","signature"]},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"type":"array","items":{"type":"string"}},{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},"index":{"description":"Field is indexed","type":"boolean"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"readRoles":{"description":"Roles allowed to read the field (\"user\" is a deprecated alias for \"editor\")","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["admin","editor","user"]}},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"unique":{"description":"Field is unique","type":"boolean"},"writeRoles":{"description":"Roles allowed to write to the field (\"user\" is a deprecated alias for \"editor\")","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["admin","editor","user"]}}},"required":["labels","name","type"],"additionalProperties":false}},"FieldsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"binding":{"description":"Read-only: internal binding reference, format not yet specified","type":"string"},"canRead":{"description":"Script expression gating field-level read access","type":"string"},"canWrite":{"description":"Script expression gating field-level write access","type":"string"},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},{"type":"array","items":{"type":"string"}}]},"expression":{"description":"Expression (for function type)","type":"string"},"expressionErrors":{"description":"Expression validation errors (for function type)","type":"array","items":{"type":"object","properties":{"column":{"type":"number","description":"Column number where the error occurred"},"line":{"type":"number","description":"Line number where the error occurred"},"message":{"type":"string","description":"Error message"}},"required":["column","line","message"]}},"index":{"description":"Field is indexed","type":"boolean"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Field name"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"optionColor":{"description":"Color expression for dchoice/dmulti fields","type":"string"},"optionIcon":{"description":"Icon expression for dchoice/dmulti fields","type":"string"},"optionName":{"description":"Display name expression for dchoice/dmulti fields","type":"string"},"options":{"description":"Options array for choice/multi fields, or selection expression for dchoice/dmulti fields","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"type":"string","description":"Stable option id"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Option name"},"order":{"type":"number","description":"Option display order"},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["id","name","order"]}},{"type":"string"}]},"readRoles":{"description":"Roles allowed to read the field","type":"array","items":{"type":"string"}},"refTableId":{"description":"Reference table id","type":"string"},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"syncedFrom":{"description":"Source column this field syncs from. Read-only unless the table has two-way sync with updates enabled, in which case every synced field except the key column is writable.","type":"string"},"type":{"type":"string","enum":["any","appointment","boolean","choice","color","date","dchoice","dmulti","file","function","html","icon","lambda","multi","number","react","reference","reverse","rowId","string","styled","time","timeinterval","timestamp","unknown","user","void"],"description":"Field type"},"unique":{"description":"Field is unique","type":"boolean"},"variant":{"description":"Field variant (for string type)","type":"string"},"writeRoles":{"description":"Roles allowed to write to the field","type":"array","items":{"type":"string"}}},"required":["name","type"]},"description":"List of fields"}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/fields/batch":{"post":{"operationId":"FieldsV1Controller_createFieldsBatch","summary":"Create multiple fields (batch)","description":"Creates multiple fields in a table within a single transaction. If any field creation fails, all changes are rolled back.\n\nThe same rules as the single-create endpoint apply per field: choice/multi fields accept an initial `options` array; dchoice/dmulti fields require an `options` expression; logic fields accept an optional `expression`. All expressions are validated after save — invalid expressions do not prevent creation but add an `expressionErrors` array to the affected field in the response.\n\n`canRead` / `canWrite` follow the single-create rules too, with one difference in effect: they are compiled before the transaction, so one field with an uncompilable guard returns 400 and no field in the batch is created.","parameters":[{"name":"moduleName","required":true,"in":"path","description":"Module name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"tableName","required":true,"in":"path","description":"Table name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"Workspace ID","schema":{"minLength":12,"maxLength":12,"pattern":"^[a-z0-9]+$","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFieldsBatchBody"}}}},"responses":{"201":{"description":"Fields created successfully. Fields with invalid expressions still return 201 but include an `expressionErrors` array.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldsResponse"}}}},"400":{"description":"Bad request — validation failure (e.g., duplicate field names in the batch, field already exists)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Workspace, module or table not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Fields"]}}}}
```

## Delete multiple fields (batch)

> Deletes multiple fields in a table within a single transaction. If any field deletion fails, all changes are rolled back.

```json
{"openapi":"3.0.0","info":{"title":"Ninox Public API","version":"1.0.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"API Key","description":"Enter your Workspace API key. \n\n API keys can be generated and managed within the **Workspace Integration** settings in the Ninox app.","in":"header","name":"Authorization","type":"http"}},"schemas":{"DeleteFieldsBatchBody":{"type":"object","properties":{"fieldNames":{"minItems":1,"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","description":"Field name"}}},"required":["fieldNames"],"additionalProperties":false},"FieldsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"binding":{"description":"Read-only: internal binding reference, format not yet specified","type":"string"},"canRead":{"description":"Script expression gating field-level read access","type":"string"},"canWrite":{"description":"Script expression gating field-level write access","type":"string"},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},{"type":"array","items":{"type":"string"}}]},"expression":{"description":"Expression (for function type)","type":"string"},"expressionErrors":{"description":"Expression validation errors (for function type)","type":"array","items":{"type":"object","properties":{"column":{"type":"number","description":"Column number where the error occurred"},"line":{"type":"number","description":"Line number where the error occurred"},"message":{"type":"string","description":"Error message"}},"required":["column","line","message"]}},"index":{"description":"Field is indexed","type":"boolean"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Field name"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"optionColor":{"description":"Color expression for dchoice/dmulti fields","type":"string"},"optionIcon":{"description":"Icon expression for dchoice/dmulti fields","type":"string"},"optionName":{"description":"Display name expression for dchoice/dmulti fields","type":"string"},"options":{"description":"Options array for choice/multi fields, or selection expression for dchoice/dmulti fields","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"type":"string","description":"Stable option id"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Option name"},"order":{"type":"number","description":"Option display order"},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["id","name","order"]}},{"type":"string"}]},"readRoles":{"description":"Roles allowed to read the field","type":"array","items":{"type":"string"}},"refTableId":{"description":"Reference table id","type":"string"},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"syncedFrom":{"description":"Source column this field syncs from. Read-only unless the table has two-way sync with updates enabled, in which case every synced field except the key column is writable.","type":"string"},"type":{"type":"string","enum":["any","appointment","boolean","choice","color","date","dchoice","dmulti","file","function","html","icon","lambda","multi","number","react","reference","reverse","rowId","string","styled","time","timeinterval","timestamp","unknown","user","void"],"description":"Field type"},"unique":{"description":"Field is unique","type":"boolean"},"variant":{"description":"Field variant (for string type)","type":"string"},"writeRoles":{"description":"Roles allowed to write to the field","type":"array","items":{"type":"string"}}},"required":["name","type"]},"description":"List of fields"}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/fields/batch":{"delete":{"operationId":"FieldsV1Controller_deleteFieldsBatch","summary":"Delete multiple fields (batch)","description":"Deletes multiple fields in a table within a single transaction. If any field deletion fails, all changes are rolled back.","parameters":[{"name":"moduleName","required":true,"in":"path","description":"Module name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"tableName","required":true,"in":"path","description":"Table name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"Workspace ID","schema":{"minLength":12,"maxLength":12,"pattern":"^[a-z0-9]+$","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFieldsBatchBody"}}}},"responses":{"200":{"description":"Fields deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldsResponse"}}}},"400":{"description":"Bad request (e.g., duplicates in request)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Fields"]}}}}
```

## Update multiple fields (batch)

> Updates multiple fields in a table within a single transaction. If any field update fails, all changes are rolled back. Same per-field rules as the single-update endpoint apply to each entry — including the \`schema:manage-permissions\` grant for permission properties and the pre-save compilation of \`canRead\` / \`canWrite\`, either of which rejects the whole batch.

```json
{"openapi":"3.0.0","info":{"title":"Ninox Public API","version":"1.0.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"API Key","description":"Enter your Workspace API key. \n\n API keys can be generated and managed within the **Workspace Integration** settings in the Ninox app.","in":"header","name":"Authorization","type":"http"}},"schemas":{"UpdateFieldsBatchBody":{"minItems":1,"type":"array","items":{"type":"object","properties":{"canRead":{"type":"string","minLength":1,"description":"Script expression that must allow reading this field's value; null removes the guard","nullable":true},"canWrite":{"type":"string","minLength":1,"description":"Script expression that must allow writing this field's value; null removes the guard","nullable":true},"expression":{"description":"Expression (for function type)","type":"string"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":100}},"name":{"description":"Field name","type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$"},"optionColor":{"description":"Color expression (for dchoice/dmulti types)","type":"string"},"optionIcon":{"description":"Icon expression (for dchoice/dmulti types)","type":"string"},"optionName":{"description":"Display name expression (for dchoice/dmulti types)","type":"string"},"options":{"description":"Options array (for choice/multi types) or selection expression (for dchoice/dmulti types)","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"description":"Stable option id (omit for new options; system assigns id)","type":"string"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","minLength":1,"description":"Option name"},"order":{"description":"Option display order","type":"integer","minimum":0,"maximum":9007199254740991},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["name"],"additionalProperties":false}},{"type":"string"}]},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"type":"array","items":{"type":"string"}},{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},"index":{"description":"Field is indexed","type":"boolean"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"readRoles":{"description":"Roles allowed to read the field (\"user\" is a deprecated alias for \"editor\")","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["admin","editor","user"]}},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"unique":{"description":"Field is unique","type":"boolean"},"writeRoles":{"description":"Roles allowed to write to the field (\"user\" is a deprecated alias for \"editor\")","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["admin","editor","user"]}},"fieldName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","description":"Name of the field to update"}},"required":["fieldName"],"additionalProperties":false}},"FieldsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"binding":{"description":"Read-only: internal binding reference, format not yet specified","type":"string"},"canRead":{"description":"Script expression gating field-level read access","type":"string"},"canWrite":{"description":"Script expression gating field-level write access","type":"string"},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},{"type":"array","items":{"type":"string"}}]},"expression":{"description":"Expression (for function type)","type":"string"},"expressionErrors":{"description":"Expression validation errors (for function type)","type":"array","items":{"type":"object","properties":{"column":{"type":"number","description":"Column number where the error occurred"},"line":{"type":"number","description":"Line number where the error occurred"},"message":{"type":"string","description":"Error message"}},"required":["column","line","message"]}},"index":{"description":"Field is indexed","type":"boolean"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Field name"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"optionColor":{"description":"Color expression for dchoice/dmulti fields","type":"string"},"optionIcon":{"description":"Icon expression for dchoice/dmulti fields","type":"string"},"optionName":{"description":"Display name expression for dchoice/dmulti fields","type":"string"},"options":{"description":"Options array for choice/multi fields, or selection expression for dchoice/dmulti fields","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"type":"string","description":"Stable option id"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Option name"},"order":{"type":"number","description":"Option display order"},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["id","name","order"]}},{"type":"string"}]},"readRoles":{"description":"Roles allowed to read the field","type":"array","items":{"type":"string"}},"refTableId":{"description":"Reference table id","type":"string"},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"syncedFrom":{"description":"Source column this field syncs from. Read-only unless the table has two-way sync with updates enabled, in which case every synced field except the key column is writable.","type":"string"},"type":{"type":"string","enum":["any","appointment","boolean","choice","color","date","dchoice","dmulti","file","function","html","icon","lambda","multi","number","react","reference","reverse","rowId","string","styled","time","timeinterval","timestamp","unknown","user","void"],"description":"Field type"},"unique":{"description":"Field is unique","type":"boolean"},"variant":{"description":"Field variant (for string type)","type":"string"},"writeRoles":{"description":"Roles allowed to write to the field","type":"array","items":{"type":"string"}}},"required":["name","type"]},"description":"List of fields"}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/fields/batch":{"patch":{"operationId":"FieldsV1Controller_updateFieldsBatch","summary":"Update multiple fields (batch)","description":"Updates multiple fields in a table within a single transaction. If any field update fails, all changes are rolled back. Same per-field rules as the single-update endpoint apply to each entry — including the `schema:manage-permissions` grant for permission properties and the pre-save compilation of `canRead` / `canWrite`, either of which rejects the whole batch.","parameters":[{"name":"moduleName","required":true,"in":"path","description":"Module name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"tableName","required":true,"in":"path","description":"Table name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"Workspace ID","schema":{"minLength":12,"maxLength":12,"pattern":"^[a-z0-9]+$","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFieldsBatchBody"}}}},"responses":{"200":{"description":"Fields updated successfully. A field with an updated expression that has syntax errors still returns 200 but includes an `expressionErrors` array.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldsResponse"}}}},"400":{"description":"Bad request (e.g., duplicate fieldName entries in the batch, field already exists)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Fields"]}}}}
```

## Get a specific field

> Retrieves detailed information about a specific field in a table. For choice/multi fields the response includes an \`options\` array with stable ids. For dchoice/dmulti fields the response includes the \`options\` expression and any configured \`optionName\`, \`optionIcon\`, \`optionColor\` formulas. For function fields the response includes the \`expression\`. Any configured \`canRead\` / \`canWrite\` permission guards are included for every type.

```json
{"openapi":"3.0.0","info":{"title":"Ninox Public API","version":"1.0.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"API Key","description":"Enter your Workspace API key. \n\n API keys can be generated and managed within the **Workspace Integration** settings in the Ninox app.","in":"header","name":"Authorization","type":"http"}},"schemas":{"FieldResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"binding":{"description":"Read-only: internal binding reference, format not yet specified","type":"string"},"canRead":{"description":"Script expression gating field-level read access","type":"string"},"canWrite":{"description":"Script expression gating field-level write access","type":"string"},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},{"type":"array","items":{"type":"string"}}]},"expression":{"description":"Expression (for function type)","type":"string"},"expressionErrors":{"description":"Expression validation errors (for function type)","type":"array","items":{"type":"object","properties":{"column":{"type":"number","description":"Column number where the error occurred"},"line":{"type":"number","description":"Line number where the error occurred"},"message":{"type":"string","description":"Error message"}},"required":["column","line","message"]}},"index":{"description":"Field is indexed","type":"boolean"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Field name"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"optionColor":{"description":"Color expression for dchoice/dmulti fields","type":"string"},"optionIcon":{"description":"Icon expression for dchoice/dmulti fields","type":"string"},"optionName":{"description":"Display name expression for dchoice/dmulti fields","type":"string"},"options":{"description":"Options array for choice/multi fields, or selection expression for dchoice/dmulti fields","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"type":"string","description":"Stable option id"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Option name"},"order":{"type":"number","description":"Option display order"},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["id","name","order"]}},{"type":"string"}]},"readRoles":{"description":"Roles allowed to read the field","type":"array","items":{"type":"string"}},"refTableId":{"description":"Reference table id","type":"string"},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"syncedFrom":{"description":"Source column this field syncs from. Read-only unless the table has two-way sync with updates enabled, in which case every synced field except the key column is writable.","type":"string"},"type":{"type":"string","enum":["any","appointment","boolean","choice","color","date","dchoice","dmulti","file","function","html","icon","lambda","multi","number","react","reference","reverse","rowId","string","styled","time","timeinterval","timestamp","unknown","user","void"],"description":"Field type"},"unique":{"description":"Field is unique","type":"boolean"},"variant":{"description":"Field variant (for string type)","type":"string"},"writeRoles":{"description":"Roles allowed to write to the field","type":"array","items":{"type":"string"}}},"description":"Field details"}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/fields/{fieldName}":{"get":{"operationId":"FieldsV1Controller_getField","summary":"Get a specific field","description":"Retrieves detailed information about a specific field in a table. For choice/multi fields the response includes an `options` array with stable ids. For dchoice/dmulti fields the response includes the `options` expression and any configured `optionName`, `optionIcon`, `optionColor` formulas. For function fields the response includes the `expression`. Any configured `canRead` / `canWrite` permission guards are included for every type.","parameters":[{"name":"fieldName","required":true,"in":"path","description":"Field name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"moduleName","required":true,"in":"path","description":"Module name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"tableName","required":true,"in":"path","description":"Table name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"Workspace ID","schema":{"minLength":12,"maxLength":12,"pattern":"^[a-z0-9]+$","type":"string"}}],"responses":{"200":{"description":"Field details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Fields"]}}}}
```

## Delete a field

> Deletes a field in a table

```json
{"openapi":"3.0.0","info":{"title":"Ninox Public API","version":"1.0.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"API Key","description":"Enter your Workspace API key. \n\n API keys can be generated and managed within the **Workspace Integration** settings in the Ninox app.","in":"header","name":"Authorization","type":"http"}},"schemas":{"FieldResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"binding":{"description":"Read-only: internal binding reference, format not yet specified","type":"string"},"canRead":{"description":"Script expression gating field-level read access","type":"string"},"canWrite":{"description":"Script expression gating field-level write access","type":"string"},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},{"type":"array","items":{"type":"string"}}]},"expression":{"description":"Expression (for function type)","type":"string"},"expressionErrors":{"description":"Expression validation errors (for function type)","type":"array","items":{"type":"object","properties":{"column":{"type":"number","description":"Column number where the error occurred"},"line":{"type":"number","description":"Line number where the error occurred"},"message":{"type":"string","description":"Error message"}},"required":["column","line","message"]}},"index":{"description":"Field is indexed","type":"boolean"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Field name"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"optionColor":{"description":"Color expression for dchoice/dmulti fields","type":"string"},"optionIcon":{"description":"Icon expression for dchoice/dmulti fields","type":"string"},"optionName":{"description":"Display name expression for dchoice/dmulti fields","type":"string"},"options":{"description":"Options array for choice/multi fields, or selection expression for dchoice/dmulti fields","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"type":"string","description":"Stable option id"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Option name"},"order":{"type":"number","description":"Option display order"},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["id","name","order"]}},{"type":"string"}]},"readRoles":{"description":"Roles allowed to read the field","type":"array","items":{"type":"string"}},"refTableId":{"description":"Reference table id","type":"string"},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"syncedFrom":{"description":"Source column this field syncs from. Read-only unless the table has two-way sync with updates enabled, in which case every synced field except the key column is writable.","type":"string"},"type":{"type":"string","enum":["any","appointment","boolean","choice","color","date","dchoice","dmulti","file","function","html","icon","lambda","multi","number","react","reference","reverse","rowId","string","styled","time","timeinterval","timestamp","unknown","user","void"],"description":"Field type"},"unique":{"description":"Field is unique","type":"boolean"},"variant":{"description":"Field variant (for string type)","type":"string"},"writeRoles":{"description":"Roles allowed to write to the field","type":"array","items":{"type":"string"}}},"description":"Field details"}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/fields/{fieldName}":{"delete":{"operationId":"FieldsV1Controller_deleteField","summary":"Delete a field","description":"Deletes a field in a table","parameters":[{"name":"fieldName","required":true,"in":"path","description":"Field name","schema":{}},{"name":"tableName","required":true,"in":"path","description":"Table name","schema":{}},{"name":"moduleName","required":true,"in":"path","description":"Module name","schema":{}},{"name":"workspaceId","required":true,"in":"path","description":"Workspace ID","schema":{}}],"responses":{"200":{"description":"Field deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Fields"]}}}}
```

## Update a field

> Updates an existing field in a table.\
> \
> \*\*choice / multi fields:\*\* \`options\` replaces the full option list. Include the stable \`id\` for existing options you want to keep; omit \`id\` for new options. Sending an options array to a non-choice field or an options expression to a non-dynamic-choice field returns 400.\
> \
> \*\*dchoice / dmulti fields:\*\* \`options\` updates the selection expression. \`optionName\`, \`optionIcon\`, and \`optionColor\` update the corresponding display-value formulas. All expressions are validated after save — if any are invalid the field is still saved and the response includes an \`expressionErrors\` array. \`optionName\`, \`optionIcon\`, \`optionColor\` cannot be sent to non-dynamic-choice fields (returns 400).\
> \
> \*\*Logic (function) fields:\*\* \`expression\` is validated after save; errors are returned in \`expressionErrors\`.\
> \
> \*\*Permission guards:\*\* \`canRead\` and \`canWrite\` are per-record Ninox Script expressions, compiled \*before\* the update — an expression that does not parse returns 400 and nothing is changed, because a guard that fails at evaluation time denies access rather than warning. Send \`null\` to remove a guard; \`'true'\` also stops it refusing anything, but keeps an expression that is still evaluated once per record. An empty string is rejected rather than read as "no guard" — only an absent guard is treated as absent, so a blank expression would be evaluated and would deny every record. \`canWrite\` is rejected for computed and system-generated types (\`function\`, \`lambda\`, \`reverse\`, \`rowId\`, \`void\`), which have no write path to guard and therefore never carry one to clear. Setting or clearing either requires the \`schema:manage-permissions\` grant.

```json
{"openapi":"3.0.0","info":{"title":"Ninox Public API","version":"1.0.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"API Key","description":"Enter your Workspace API key. \n\n API keys can be generated and managed within the **Workspace Integration** settings in the Ninox app.","in":"header","name":"Authorization","type":"http"}},"schemas":{"UpdateFieldBody":{"type":"object","properties":{"canRead":{"type":"string","minLength":1,"description":"Script expression that must allow reading this field's value; null removes the guard","nullable":true},"canWrite":{"type":"string","minLength":1,"description":"Script expression that must allow writing this field's value; null removes the guard","nullable":true},"expression":{"description":"Expression (for function type)","type":"string"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":100}},"name":{"description":"Field name","type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$"},"optionColor":{"description":"Color expression (for dchoice/dmulti types)","type":"string"},"optionIcon":{"description":"Icon expression (for dchoice/dmulti types)","type":"string"},"optionName":{"description":"Display name expression (for dchoice/dmulti types)","type":"string"},"options":{"description":"Options array (for choice/multi types) or selection expression (for dchoice/dmulti types)","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"description":"Stable option id (omit for new options; system assigns id)","type":"string"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","minLength":1,"description":"Option name"},"order":{"description":"Option display order","type":"integer","minimum":0,"maximum":9007199254740991},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["name"],"additionalProperties":false}},{"type":"string"}]},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"type":"array","items":{"type":"string"}},{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},"index":{"description":"Field is indexed","type":"boolean"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"readRoles":{"description":"Roles allowed to read the field (\"user\" is a deprecated alias for \"editor\")","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["admin","editor","user"]}},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"unique":{"description":"Field is unique","type":"boolean"},"writeRoles":{"description":"Roles allowed to write to the field (\"user\" is a deprecated alias for \"editor\")","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["admin","editor","user"]}}},"additionalProperties":false},"FieldResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"binding":{"description":"Read-only: internal binding reference, format not yet specified","type":"string"},"canRead":{"description":"Script expression gating field-level read access","type":"string"},"canWrite":{"description":"Script expression gating field-level write access","type":"string"},"defaultValue":{"description":"Default value applied when a record is created: a literal value (an array of option ids for multi/dmulti), or a script expression (as { $nx: <script> }) evaluated at creation time","anyOf":[{"type":"object","properties":{"$nx":{"type":"string","description":"Script expression"}},"required":["$nx"]},{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string"}],"nullable":true},{"type":"array","items":{"type":"string"}}]},"expression":{"description":"Expression (for function type)","type":"string"},"expressionErrors":{"description":"Expression validation errors (for function type)","type":"array","items":{"type":"object","properties":{"column":{"type":"number","description":"Column number where the error occurred"},"line":{"type":"number","description":"Line number where the error occurred"},"message":{"type":"string","description":"Error message"}},"required":["column","line","message"]}},"index":{"description":"Field is indexed","type":"boolean"},"labels":{"description":"Field labels (localized)","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Field name"},"onUpdate":{"description":"Script expression run as a row trigger when the field value changes","type":"string"},"optionColor":{"description":"Color expression for dchoice/dmulti fields","type":"string"},"optionIcon":{"description":"Icon expression for dchoice/dmulti fields","type":"string"},"optionName":{"description":"Display name expression for dchoice/dmulti fields","type":"string"},"options":{"description":"Options array for choice/multi fields, or selection expression for dchoice/dmulti fields","anyOf":[{"type":"array","items":{"type":"object","properties":{"color":{"description":"Option color (hex string)","type":"string"},"icon":{"description":"Option icon name","type":"string"},"id":{"type":"string","description":"Stable option id"},"labels":{"description":"Localized option labels","type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string","description":"Option name"},"order":{"type":"number","description":"Option display order"},"textColor":{"description":"Option text color (hex string)","type":"string"}},"required":["id","name","order"]}},{"type":"string"}]},"readRoles":{"description":"Roles allowed to read the field","type":"array","items":{"type":"string"}},"refTableId":{"description":"Reference table id","type":"string"},"required":{"description":"Field is required","type":"boolean"},"search":{"description":"Field is searchable","type":"boolean"},"syncedFrom":{"description":"Source column this field syncs from. Read-only unless the table has two-way sync with updates enabled, in which case every synced field except the key column is writable.","type":"string"},"type":{"type":"string","enum":["any","appointment","boolean","choice","color","date","dchoice","dmulti","file","function","html","icon","lambda","multi","number","react","reference","reverse","rowId","string","styled","time","timeinterval","timestamp","unknown","user","void"],"description":"Field type"},"unique":{"description":"Field is unique","type":"boolean"},"variant":{"description":"Field variant (for string type)","type":"string"},"writeRoles":{"description":"Roles allowed to write to the field","type":"array","items":{"type":"string"}}},"description":"Field details"}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/fields/{fieldName}":{"patch":{"operationId":"FieldsV1Controller_updateField","summary":"Update a field","description":"Updates an existing field in a table.\n\n**choice / multi fields:** `options` replaces the full option list. Include the stable `id` for existing options you want to keep; omit `id` for new options. Sending an options array to a non-choice field or an options expression to a non-dynamic-choice field returns 400.\n\n**dchoice / dmulti fields:** `options` updates the selection expression. `optionName`, `optionIcon`, and `optionColor` update the corresponding display-value formulas. All expressions are validated after save — if any are invalid the field is still saved and the response includes an `expressionErrors` array. `optionName`, `optionIcon`, `optionColor` cannot be sent to non-dynamic-choice fields (returns 400).\n\n**Logic (function) fields:** `expression` is validated after save; errors are returned in `expressionErrors`.\n\n**Permission guards:** `canRead` and `canWrite` are per-record Ninox Script expressions, compiled *before* the update — an expression that does not parse returns 400 and nothing is changed, because a guard that fails at evaluation time denies access rather than warning. Send `null` to remove a guard; `'true'` also stops it refusing anything, but keeps an expression that is still evaluated once per record. An empty string is rejected rather than read as \"no guard\" — only an absent guard is treated as absent, so a blank expression would be evaluated and would deny every record. `canWrite` is rejected for computed and system-generated types (`function`, `lambda`, `reverse`, `rowId`, `void`), which have no write path to guard and therefore never carry one to clear. Setting or clearing either requires the `schema:manage-permissions` grant.","parameters":[{"name":"fieldName","required":true,"in":"path","description":"Field name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"moduleName","required":true,"in":"path","description":"Module name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"tableName","required":true,"in":"path","description":"Table name","schema":{"minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","type":"string"}},{"name":"workspaceId","required":true,"in":"path","description":"Workspace ID","schema":{"minLength":12,"maxLength":12,"pattern":"^[a-z0-9]+$","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFieldBody"}}}},"responses":{"200":{"description":"Field updated successfully. If the field contains an updated expression (function, dchoice, dmulti) and it has syntax errors, the response still returns 200 but includes an `expressionErrors` array.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldResponse"}}}},"400":{"description":"Bad request (e.g., field already exists)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Fields"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ninox.com/ninox-api/api-reference/api-endpoints/fields.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.