Skip to content
excalibase
rest
REST APIstable

Excalibase REST

Every table your API permissions expose is a REST resource. No controllers, no DTOs: add a table in Studio or with SQL and GET /api/v1/{table} answers a few seconds later. The same engine and the same permissions answer GraphQL; pick whichever fits the call.

On Excalibase Cloud

Every route starts with your project id. First connect and exchange a key for a token, then send it as Authorization: Bearer $TOKEN:

RouteWhat it does
GET /{projectId}/api/v1/{table}List rows: filter, sort, paginate, pick columns
POST /{projectId}/api/v1/{table}Insert a row, or an array of rows
PATCH /{projectId}/api/v1/{table}?col=eq.valueUpdate the rows a filter matches
PUT /{projectId}/api/v1/{table}?col=eq.valueReplace the rows a filter matches
DELETE /{projectId}/api/v1/{table}?col=eq.valueDelete the rows a filter matches
GET or POST /{projectId}/api/v1/rpc/{function}Call a tracked function
GET /{projectId}/api/v1 with Accept: application/openapi+jsonThe OpenAPI 3 document for what your role can reach
curl -s "$BASE/$PROJECT_ID/api/v1/feedback_posts?select=id,kind,body&order=id.desc&limit=2" \
  -H "Authorization: Bearer $TOKEN"

A single row is a filter, not a path: ?id=eq.1. There is no /{table}/{id} route.

Which tables, columns and rows a caller reaches is decided by the API permissions of the role in their token. A request with no token runs as anon.

curl -s "$BASE/$PROJECT_ID/api/v1" -H "Accept: application/openapi+json" | jq '.paths | keys'

Import that document into Swagger UI, Postman or Insomnia.

What you get

  • Filter operators: eq, gt, ilike, in, is.null, JSON and array operators, full-text search. See Filtering.
  • Column selection: ?select=id,kind.
  • Ordering and pagination: order=id.desc, limit and offset, or a Range header. Prefer: count=exact adds a total where your role may count.
  • Writes with a dry run: Prefer: tx=rollback runs the statement and rolls it back.
  • Exact numbers: bigint and decimal columns arrive as strings ("19.90"), and are taken back as a string or a number. See Numbers.
  • Typed errors: 409 for a duplicate, 400 for a bad reference or value, 403 for a refused permission, each with a code. See Errors.

Aggregations and nested relationships are GraphQL features. See Aggregations and Relationships for the GraphQL form, and Subscriptions for realtime.

Self-hosting

This section is for running the engine yourself.

  • A standalone engine serves the same /{projectId}/api/v1/{table} routes; the quick start below gives the local ports.
  • The standalone excalibase-rest service (the separate repository) also serves routes a cloud project does not: GET /api/v1/{table}/{id}, GET /api/v1/{table}/{id1},{id2} for composite keys, /api/v1/openapi.json and /api/v1/openapi.yaml, an SSE stream at /api/v1/{table}/changes and a WebSocket at /ws/{table}/changes. These answer 404 on Excalibase Cloud. The replacements there are ?id=eq.1, the Accept: application/openapi+json request above, and GraphQL subscriptions.
DatabaseStatus
PostgreSQLSupported (PG 15+)
MySQLSupported
OraclePlanned

github.com/excalibase/excalibase-graphql: REST and GraphQL ship from the same engine.