Skip to content
Beta — Truss is in public beta. Documentation is actively updated but may not reflect the latest changes. Report issues on GitHub.

REST API

The Truss API runs on port 8787. There are two API layers:

  • Client API (/v1/*) — for your applications, requires API keys
  • Dashboard API (/api/*) — for the Truss dashboard, uses session cookies

All client API endpoints require an API key via the apikey header.

Terminal window
# All /v1/* requests need an API key
curl http://localhost:8787/v1/db/users \
-H "apikey: truss_pk_your_key"

Two key types: anon (prefix truss_pk_) respects RLS, service_role (prefix truss_sk_) bypasses non-FORCE RLS. A bare anon key maps to the Postgres anon role — SELECT-only and default-deny: without a JWT it can only read, and only rows a policy allows. Adding a verified JWT via Authorization: Bearer promotes the request to the authenticated role (full DML, still RLS-enforced). See API Keys.

POST /v1/sql — Execute arbitrary SQL (service_role only)

{
"sql": "SELECT * FROM users WHERE active = $1",
"params": [true],
"row_limit": 10000,
"timeout": 15000
}

timeout is in milliseconds (default 15000, max 30000). row_limit defaults to 10000 (max 50000) and is only applied when the query has no explicit LIMIT.

Response:

{
"rows": [...],
"rowCount": 42,
"columns": [{"name": "id", "dataTypeID": 23, "typeName": "int4"}],
"command": "SELECT"
}

POST /v1/sql/transaction — Execute multiple statements in a transaction (service_role only)

{
"statements": [
{"sql": "INSERT INTO orders (total) VALUES ($1)", "params": [99.99]},
{"sql": "UPDATE inventory SET count = count - 1 WHERE id = $1", "params": [5]}
]
}

Max 20 statements. Rolls back on any failure.

| Method | Endpoint | Description | Key type | |--------|----------|-------------|----------| | GET | /v1/db/:table | Select rows | anon (RLS-enforced) or service_role | | POST | /v1/db/:table | Insert row(s) | authenticated (anon key + JWT) or service_role — a bare anon key is read-only | | PATCH | /v1/db/:table | Update rows (filter required) | authenticated (anon key + JWT) or service_role — a bare anon key is read-only | | DELETE | /v1/db/:table | Delete rows (filter required) | authenticated (anon key + JWT) or service_role — a bare anon key is read-only | | POST | /v1/db/rpc/:function | Call a Postgres function | authenticated (anon key + JWT) or service_role — a bare anon key is read-only |

| Param | Example | Description | |-------|---------|-------------| | select | select=id,name,email | Columns to return | | order | order=created_at.desc | Sort order | | limit | limit=50 | Max rows (default 1000, max 10000) | | offset | offset=100 | Skip rows | | Filter | status=eq.active | Where clause (see filter operators) |

eq, neq, gt, gte, lt, lte, like, ilike, is, in

Examples: ?age=gt.18, ?name=ilike.*john*, ?id=in.(1,2,3), ?deleted=is.null

All management endpoints require a service_role key, with two exceptions: GET /v1/gateway/health and GET /v1/oauth2/discovery only need a valid API key (any anon or service_role key works).

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/status | Comprehensive platform overview | | GET | /v1/modules | Enabled modules | | GET | /v1/metrics | API consumption metrics | | GET | /v1/audit-logs | Audit log entries |

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/projects | List all projects | | GET | /v1/projects/:id | Full project detail with keys, tables, storage | | PATCH | /v1/projects/:id | Update project (name, status) |

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/database/schema | Full schema introspection | | GET | /v1/database/tables/:schema/:table | Table detail (columns, PKs, FKs, indexes, triggers, RLS) | | GET | /v1/branches | List database branches | | GET | /v1/backups | List backups |

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/keys | List all keys | | POST | /v1/keys | Create a key | | DELETE | /v1/keys/:id | Revoke a key | | POST | /v1/keys/:id/rotate | Rotate a key |

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/auth/identities | List identities | | GET | /v1/auth/identities/:id | Identity detail |

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/storage/buckets | List buckets with object counts |

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/webhooks | List webhooks with delivery stats | | GET | /v1/webhooks/:id | Webhook detail with recent logs |

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/realtime | Realtime engine status + subscriptions |

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/oauth2/clients | List OAuth2 clients | | POST | /v1/oauth2/clients | Create OAuth2 client | | DELETE | /v1/oauth2/clients/:id | Delete OAuth2 client | | GET | /v1/oauth2/discovery | OIDC discovery document |

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/gateway/health | Gateway health check | | GET | /v1/gateway/rules | List access rules |

All errors return a consistent JSON structure:

{
"error": "Human-readable error message",
"code": "POSTGRES_ERROR_CODE",
"detail": "Additional detail from Postgres",
"hint": "Suggested fix"
}

Rate limiting is opt-in per API key. In the open-source core there is no default limit — keys are unlimited unless you set a per-key rate_limit (requests/minute). Every response still carries the limit headers; when a key is unlimited they report -1:

X-RateLimit-Limit: -1
X-RateLimit-Remaining: -1

When a per-key limit is configured, the headers show the limit and the remaining count in the current 60-second window, and the API returns 429 Too Many Requests once the limit is exceeded.