Softr Database API

The Softr Database API lets you integrate your Softr data with external systems. The API follows REST semantics, uses JSON to encode objects, and requires all requests to be made over HTTPS. Download the OpenAPI specification to import into tools like Postman or use for code generation.

Video Introduction

Data Model

The API is organized around four core resources:

Database — A top-level container that belongs to a workspace. Each database holds one or more tables.
Table — A structured collection of records, similar to a spreadsheet or database table. Each table has a set of fields and one or more views.
Field — A column definition on a table. Fields have a type (e.g. SINGLE_LINE_TEXT, NUMBER, SELECT) and optional configuration. Some fields are read-only (computed or system-managed).
Record — A single row of data in a table. Record values are stored in a fields object, keyed by field ID. Responses can use field names instead (?fieldNames=true); requests always use field IDs.

Every resource is identified by its ID.

Authentication

All requests require a Personal Access Token (PAT) passed in the Softr-Api-Key header:

curl -X GET 'https://tables-api.softr.io/api/v1/databases' \
  -H 'Softr-Api-Key: <your-token>'

Tokens are scoped to one or more workspaces — you can only access databases within your authorized workspaces. See Authorisation for how to generate a token.

Quick Start

1. List your databases:

curl -X GET 'https://tables-api.softr.io/api/v1/databases' \
  -H 'Softr-Api-Key: <your-token>'

2. Get records from a table:

curl -X GET 'https://tables-api.softr.io/api/v1/databases/{databaseId}/tables/{tableId}/records?limit=10&fieldNames=true' \
  -H 'Softr-Api-Key: <your-token>'

3. Create a record (the keys are field IDs; Get Single Table lists a table’s fields with their IDs):

curl -X POST 'https://tables-api.softr.io/api/v1/databases/{databaseId}/tables/{tableId}/records' \
  -H 'Softr-Api-Key: <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fields": {
      "<name field ID>": "Jane Doe",
      "<email field ID>": "jane@example.com"
    }
  }'

Response Format

Success (single item)

{
  "data": { ... },
  "metadata": null
}

Success (paginated list)

{
  "data": [ ... ],
  "metadata": {
    "offset": 0,
    "limit": 20,
    "total": 100
  }
}

Error

{
  "message": "Human-readable error message",
  "errorCode": "MACHINE_READABLE_CODE",
  "details": {
    "fieldId": "Additional context",
    "traceId": "abc-123"
  }
}

Error Codes

Code	HTTP Status	Description
`BAD_REQUEST`	400	Invalid request format or data
`VALIDATION_ERROR`	400	Field validation failed
`UNKNOWN_FIELD`	400	Unrecognized field in request
`UNAUTHORIZED`	401	Missing or invalid token
`QUOTA_EXCEEDED`	402	Plan quota limit reached
`FORBIDDEN`	403	Insufficient permissions
`RESOURCE_NOT_FOUND`	404	Resource does not exist
`CONSTRAINT_VIOLATION`	409	Data constraint violation (e.g. duplicate unique value)
`PAYLOAD_TOO_LARGE`	413	Request body exceeds 64 MB
`TOO_MANY_REQUESTS`	429	Rate limit exceeded
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable

Pagination

All list endpoints support offset-based pagination:

Parameter	Default	Max	Description
`offset`	`0`	—	Number of records to skip
`limit`	`20`	`200`	Number of records per page

The response metadata includes a total count. To iterate through all records:

GET .../records?offset=0&limit=100    → records 1–100
GET .../records?offset=100&limit=100  → records 101–200
GET .../records?offset=200&limit=100  → records 201–300

Stop when offset >= metadata.total.

Using Field Names

By default, the fields object in record responses uses field IDs as keys. Pass ?fieldNames=true on any record endpoint to get human-readable field names in the response instead:

# With field IDs (default)
GET .../records
→ { "fields": { "fld_abc123": "Jane Doe" } }

# With field names
GET .../records?fieldNames=true
→ { "fields": { "Full Name": "Jane Doe" } }

fieldNames changes the response only. The fields of a create or update request and the field references of a search (leftSide, sortingField) always take field IDs; a field name there fails with Unknown field.

Building Blocks

Add and Manage Users

Publishing

Application Settings

Integrations

Video Introduction

Data Model

Authentication

Quick Start

Response Format

Success (single item)

Success (paginated list)

Error

Error Codes

Using Field Names

Quick Links

​Video Introduction

​Data Model

​Authentication

​Quick Start

​Response Format

​Success (single item)

​Success (paginated list)

​Error

​Error Codes

​Pagination

​Using Field Names

​Quick Links

Video Introduction

Data Model

Authentication

Quick Start

Response Format

Success (single item)

Success (paginated list)

Error

Error Codes

Pagination

Using Field Names

Quick Links