# Records

## Get records from a table

> Retrieves paginated rows from a table with optional filtering and sorting

```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":{"RowsResponse":{"type":"object","properties":{"data":{"description":"List of rows","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"values":{"type":"object","additionalProperties":{"oneOf":[{"type":"boolean"},{},{"type":"number"},{"type":"string"}]}}},"required":["id","values"]}},"meta":{"type":"object","properties":{"filter":{"description":"Applied filter conditions","type":"object","additionalProperties":{"oneOf":[{"type":"boolean"},{},{"type":"number"},{"type":"string"}]}},"sort":{"description":"Applied sort field","type":"string"}},"required":["filter","sort"]},"page_info":{"description":"Pagination information","type":"object","properties":{"has_more":{"description":"Whether more rows are available","type":"boolean"},"limit":{"description":"Maximum rows per page","type":"number"},"offset":{"description":"Current offset","type":"number"}},"required":["has_more","limit","offset"]}},"required":["data","page_info"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"description":"Error message","type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/records":{"get":{"operationId":"RowsV1Controller_getRows","summary":"Get records from a table","description":"Retrieves paginated rows from a table with optional filtering and sorting","parameters":[{"name":"offset","required":false,"in":"query","description":"Number of rows to skip (starts with 0)","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of rows to return (1-100)","schema":{"type":"number"}},{"name":"fields","required":false,"in":"query","description":"Comma-separated list of field names to include","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Field name to sort by","schema":{"type":"string"}},{"name":"filter","required":false,"in":"query","description":"Filter conditions as a JSON string (e.g., {\"email\": \"test@example.com\"})","schema":{"type":"string"}},{"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":"Rows retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowsResponse"}}}},"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":["Records"]}}}}
```

## Create records in a table

> Creates new records in an existing table (max. 6MB payload size)

```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":{"AddRowsBody":{"type":"object","properties":{"records":{"description":"Array of records to add to the target table","type":"array","minItems":1,"items":{"type":"object","additionalProperties":{}}}},"required":["records"]},"CreateRowsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"ids":{"description":"Created row ids","type":"array","items":{"type":"string"}}},"required":["ids"]}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"description":"Error message","type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/records":{"post":{"operationId":"RowsV1Controller_addRows","summary":"Create records in a table","description":"Creates new records in an existing table (max. 6MB payload size)","parameters":[{"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":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRowsBody"}}}},"responses":{"201":{"description":"Records created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRowsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Records"]}}}}
```

## Delete records from a table

> Deletes existing records from a table in a single transaction. If any record id is invalid, does not exist, or 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":{"DeleteRowsBody":{"type":"object","properties":{"records":{"description":"Array of record ids to delete","type":"array","minItems":1,"items":{"type":"integer","minimum":-9007199254740991,"exclusiveMinimum":false,"maximum":9007199254740991,"exclusiveMaximum":false}}},"required":["records"]},"DeleteRowsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"deletedIds":{"description":"Deleted row ids","type":"array","items":{"type":"string"}}},"required":["deletedIds"]}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"description":"Error message","type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/records":{"delete":{"operationId":"RowsV1Controller_deleteRows","summary":"Delete records from a table","description":"Deletes existing records from a table in a single transaction. If any record id is invalid, does not exist, or deletion fails, all changes are rolled back.","parameters":[{"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":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteRowsBody"}}}},"responses":{"200":{"description":"Records deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteRowsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found (workspace, module, table, or record)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Records"]}}}}
```

## Update records in a table

> Updates existing records in a table (max. 6MB payload size). Each record must include an \`id\` field referencing an existing record. The update is transactional — if any record fails validation or does not exist, all changes are rolled back.\
> \
> \*\*Field type rules:\*\*\
> \- \`multi\` — must be an \*\*array of strings\*\* (e.g. \`\["Gold", "Silver"]\`). A plain string is not accepted.\
> \- \`choice\` — a single string (e.g. \`"Gold"\`) or an array of strings.\
> \- \`boolean\` — \`true\` or \`false\` only; numeric \`1\`/\`0\` are not accepted.\
> \- \`number\` — a finite number or a numeric string (e.g. \`"42.5"\`).\
> \- \`date\` / \`timestamp\` / \`appointment\` — ISO 8601 string or Unix timestamp (ms).\
> \- Any field may be set to \`null\` to clear its value.

```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":{"UpdateRowsBody":{"type":"object","properties":{"records":{"description":"Array of records to update (each must include an id field as a positive integer)","type":"array","minItems":1,"items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"exclusiveMinimum":false,"maximum":9007199254740991,"exclusiveMaximum":false}},"required":["id"]}}},"required":["records"]},"UpdateRowsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"updatedIds":{"description":"Updated row ids","type":"array","items":{"type":"string"}}},"required":["updatedIds"]}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"description":"Error message","type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/records":{"patch":{"operationId":"RowsV1Controller_updateRows","summary":"Update records in a table","description":"Updates existing records in a table (max. 6MB payload size). Each record must include an `id` field referencing an existing record. The update is transactional — if any record fails validation or does not exist, all changes are rolled back.\n\n**Field type rules:**\n- `multi` — must be an **array of strings** (e.g. `[\"Gold\", \"Silver\"]`). A plain string is not accepted.\n- `choice` — a single string (e.g. `\"Gold\"`) or an array of strings.\n- `boolean` — `true` or `false` only; numeric `1`/`0` are not accepted.\n- `number` — a finite number or a numeric string (e.g. `\"42.5\"`).\n- `date` / `timestamp` / `appointment` — ISO 8601 string or Unix timestamp (ms).\n- Any field may be set to `null` to clear its value.","parameters":[{"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":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRowsBody"}}}},"responses":{"200":{"description":"Records updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRowsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found (workspace, module, table, or record)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload too large (max 6 MB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Records"]}}}}
```

## Import records from CSV file

> Import records from a CSV file into an existing table.\
>         \
> The endpoint accepts multipart/form-data with:\
> \- A CSV file (max 50 MB)\
> \- Optional parsing and import options\
> \
> \*\*Auto-mapping\*\*: By default, CSV columns are automatically mapped to table fields by matching column header names to field names (case-insensitive).\
> \
> \*\*Import Modes\*\*:\
> \- \`append\`: Always create new records (default)\
> \- \`update\`: Only update existing records (requires key field mappings)\
> \- \`upsert\`: Update existing records or create new ones (requires key field mappings)\
> \
> \*\*Field Mappings\*\*: Optionally provide explicit mappings to control which CSV columns map to which table fields, and which fields are used as keys for update/upsert operations.\
> \
> The entire import is processed within a single transaction - if any record fails to import, 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":{"ImportCSVResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"rowsImported":{"description":"Number of rows successfully imported","type":"number"},"rowsSkipped":{"description":"Number of rows skipped (for update mode when no match is found)","type":"number"},"rowsUpdated":{"description":"Number of existing rows updated","type":"number"}},"required":["rowsImported","rowsSkipped","rowsUpdated"]}},"required":["data"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"description":"Error message","type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/workspace/{workspaceId}/modules/{moduleName}/tables/{tableName}/records/import/csv":{"post":{"operationId":"RowsV1Controller_importCSV","summary":"Import records from CSV file","description":"Import records from a CSV file into an existing table.\n        \nThe endpoint accepts multipart/form-data with:\n- A CSV file (max 50 MB)\n- Optional parsing and import options\n\n**Auto-mapping**: By default, CSV columns are automatically mapped to table fields by matching column header names to field names (case-insensitive).\n\n**Import Modes**:\n- `append`: Always create new records (default)\n- `update`: Only update existing records (requires key field mappings)\n- `upsert`: Update existing records or create new ones (requires key field mappings)\n\n**Field Mappings**: Optionally provide explicit mappings to control which CSV columns map to which table fields, and which fields are used as keys for update/upsert operations.\n\nThe entire import is processed within a single transaction - if any record fails to import, all changes are rolled back.","parameters":[{"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":{}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"CSV file to import (max 50 MB)"},"hasHeader":{"type":"boolean","default":true,"description":"Whether the CSV file has a header row"},"delimiter":{"type":"string","description":"CSV delimiter character (auto-detected if not specified)"},"quoteChar":{"type":"string","default":"\"","description":"CSV quote character"},"encoding":{"type":"string","enum":["utf8","ascii","latin1","iso-latin1","utf16","windows-cp1252"],"default":"utf8","description":"CSV file encoding"},"importMode":{"type":"string","enum":["append","update","upsert"],"default":"append","description":"Import mode: append (insert all), update (update existing only), upsert (insert or update)"},"numberFormat":{"type":"string","enum":["us","european"],"default":"us","description":"Number format for parsing numeric values"},"batchSize":{"type":"integer","minimum":10,"maximum":200,"default":100,"description":"Number of records to process per batch"},"mappings":{"type":"string","description":"JSON array of field mappings: [{\"csvColumnName\": \"Name\", \"fieldName\": \"name\", \"updatePolicy\": \"key\"}]"}}}}}},"responses":{"201":{"description":"CSV import completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportCSVResponse"}}}},"400":{"description":"Bad request (invalid CSV, missing file, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Table not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"File too large (max 50 MB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Records"]}}}}
```


---

# Agent Instructions: 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:

```
GET https://docs.ninox.com/ninox-api/de/api-reference/api-endpoints/records.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.