REST API
Everything you can do in the interface is available through the REST API. Use it to sync data with other systems, build custom front ends or automate administration.
API documentation of your server
- Database API docs – every database has generated documentation with
your own table and field names. Open a database’s ⋯ menu → View API
docs, or go to
/api-docs. - OpenAPI spec –
/api/redoc/on the backend shows every endpoint;/api/schema.jsondownloads the spec for code generators and Postman.
Database tokens
Database tokens are the recommended way to authenticate integrations.
A database token gives access to the rows of one workspace, with separate create / read / update / delete permissions, optionally limited to certain databases or tables.
- Settings → Database tokens → Create token.
- Name it and choose the workspace.
- Adjust the permissions and copy the token.
Use it with the Token prefix:
curl -H "Authorization: Token YOUR_TOKEN" \
"https://your-server/api/database/rows/table/42/?user_field_names=true"
user_field_names=true makes the API use field names instead of ids
(field_1234).
Rows
| Action | Request |
|---|---|
| List rows | GET /api/database/rows/table/{table_id}/?user_field_names=true&size=100&page=1 |
| Search | add &search=acme |
| Filter | add &filter__Status__single_select_equal=3 or a JSON filters= parameter |
| Sort | add &order_by=-Amount,Name |
| Only a view | add &view_id={view_id} to apply that view’s filters and sorts |
| Get a row | GET /api/database/rows/table/{table_id}/{row_id}/ |
| Create | POST /api/database/rows/table/{table_id}/ |
| Update | PATCH /api/database/rows/table/{table_id}/{row_id}/ |
| Delete | DELETE /api/database/rows/table/{table_id}/{row_id}/ |
| Batch | POST, PATCH or DELETE on /api/database/rows/table/{table_id}/batch/ (up to 200 rows) |
Example: create a row
curl -X POST "https://your-server/api/database/rows/table/42/?user_field_names=true" \
-H "Authorization: Token YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"Name": "Northwind Labs", "Amount": 1240, "Stage": "Won"}'
Link fields take a list of row ids (or primary values), select fields an
option id or value, file fields a list of {"name": "..."} objects returned
by the upload endpoint (POST /api/user-files/upload-file/).
Example in Python
import requests
BASE = "https://your-server/api/database/rows/table/42/"
HEADERS = {"Authorization": "Token YOUR_TOKEN"}
rows = requests.get(BASE, headers=HEADERS,
params={"user_field_names": "true", "size": 200}).json()
for row in rows["results"]:
print(row["id"], row["Name"])
Example in JavaScript
const res = await fetch(
'https://your-server/api/database/rows/table/42/?user_field_names=true',
{ headers: { Authorization: 'Token YOUR_TOKEN' } }
)
const { results } = await res.json()
JWT authentication (full API)
Database tokens only cover rows. For everything else (workspaces, applications, fields, views, projects) sign in and use a JWT:
curl -X POST https://your-server/api/user/token-auth/ \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "..."}'
Send the returned access_token as Authorization: JWT <token>. It is valid
for a short time; renew it with POST /api/user/token-refresh/ and the
refresh_token.
Project API
| Request | Description |
|---|---|
GET /api/projects/workspace/{workspace_id}/ |
List projects (POST creates one). |
GET /api/projects/{id}/context/ |
The project briefing. |
GET /api/projects/{id}/memories/search/?q= |
Search memory. |
GET /api/projects/{id}/members/ |
Project members. |
GET or POST /api/projects/reports/{id}/render/ |
Render a report or preview a definition. |
POST /api/projects/reports/{id}/snapshot/ |
Take a snapshot. |
GET /api/projects/{id}/agent-actions/ |
Agent activity log. |
POST /api/projects/agent-actions/{id}/approve/ (reject/, undo/) |
Decide on agent actions. |
GET /api/projects/public/{handle}/{project}/{report}/ |
Data of a published report (no authentication). |
Rate limits and errors
Errors come back as JSON with an error code and a detail message, for
example ERROR_USER_NOT_IN_GROUP or ERROR_INVALID_REPORT_DEFINITION. Send
Content-Type: application/json on every request with a body, or the server
answers 415 Unsupported Media Type.