Integrate

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.json downloads 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.

  1. Settings → Database tokens → Create token.
  2. Name it and choose the workspace.
  3. 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.