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

Pagination

All list endpoints support offset-based pagination:

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.

Quick Links

• Authorisation
• Rate Limiting
• Databases
• Tables
• Table Fields
• Records
• Search & Filtering