Skip to content
excalibase
quickstart
REST APIstable

REST Quick Start

On Excalibase Cloud

You need a project and a publishable key. Follow Connect to your project for the variables below and the token exchange; the examples run against the public demo project.

BASE=https://api.excalibase.io
PROJECT_ID=proj-jfp7kx46kb
KEY=esk_pub_live_Tb2pe6iauenJiWtTdBDMbeMp
TOKEN=$(curl -s -X POST "$BASE/auth/$PROJECT_ID/$PROJECT_ID/token" \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"api_key\",\"api_key\":\"$KEY\"}" | jq -r .accessToken)

A table answers once your role has a permission on it: in Studio open Database > Tables and set the API permissions. Until then it answers 404.

List with a filter

curl -s "$BASE/$PROJECT_ID/api/v1/feedback_posts?kind=eq.idea&select=id,kind,body&limit=10" \
  -H "Authorization: Bearer $TOKEN"
{ "data": [{ "id": "1", "kind": "idea", "body": "Welcome! Post an idea, a bug or a question, and upvote the ones you agree with." }] }

One row

A row is a filter on its key; there is no /{table}/{id} route.

curl -s "$BASE/$PROJECT_ID/api/v1/feedback_posts?id=eq.1" \
  -H "Authorization: Bearer $TOKEN"

Insert

The demo project lets anon add a post (kind, body, author_name). Prefer: return=representation returns the new row, and tx=rollback makes this one a dry run: the statement runs, then rolls back. Drop tx=rollback to keep the row.

curl -s -X POST "$BASE/$PROJECT_ID/api/v1/feedback_posts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation, tx=rollback" \
  -d '{"kind": "idea", "body": "Dark mode for the board", "author_name": "Ada"}'

Update and delete

PATCH changes the rows a filter matches, PUT replaces them and DELETE removes them. The demo project grants anon no update or delete, so these answer 403 permission_denied; in a project whose role holds the permission they answer 200 with the rows.

curl -s -X PATCH "$BASE/$PROJECT_ID/api/v1/feedback_posts?id=eq.1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Welcome! (edited)"}'
curl -s -X DELETE "$BASE/$PROJECT_ID/api/v1/feedback_posts?id=eq.1" \
  -H "Authorization: Bearer $TOKEN"

Call a function

A Postgres function the project tracks is reachable at /rpc/{function}. The demo project tracks link_shortener_create:

curl -s -X POST "$BASE/$PROJECT_ID/api/v1/rpc/link_shortener_create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Prefer: tx=rollback" \
  -d '{"url": "https://example.com/docs"}'

OpenAPI

curl -s "$BASE/$PROJECT_ID/api/v1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/openapi+json" | jq '.info'

Import the document into Swagger UI, Postman or Insomnia. It lists the tables and columns the caller's role can reach.

Self-hosting

Everything above works the same against your own stack: replace https://api.excalibase.io with your API host. This section covers the standalone excalibase-rest service, which has its own local ports and a few extra routes. The extra routes (get by primary key, openapi.json and openapi.yaml, the SSE and WebSocket change streams) are self-hosted only; they answer 404 on Excalibase Cloud.

Docker (recommended)

git clone https://github.com/excalibase/excalibase-rest.git
cd excalibase-rest
cp .env.example .env
# Edit .env with your database credentials
docker-compose up -d

API runs on port 20000 by default.

Configuration

application.yaml

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/yourdb
    username: youruser
    password: yourpass

app:
  allowed-schema: public
  max-page-size: 1000
  default-page-size: 100

Configuration reference

KeyDefaultDescription
app.allowed-schemapublicPostgreSQL schema to expose
app.default-page-size100Rows returned when no limit is specified
app.max-page-size1000Maximum rows per request
server.port20000HTTP port
app.nats.enabledfalseEnable CDC real-time subscriptions (SSE + WebSocket)
app.nats.urlnats://localhost:4222NATS server URL (requires JetStream)
app.nats.stream-namecdc-streamNATS JetStream stream name

Environment variables

SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/yourdb
SPRING_DATASOURCE_USERNAME=youruser
SPRING_DATASOURCE_PASSWORD=yourpass
APP_ALLOWED_SCHEMA=public
APP_NATS_ENABLED=true
APP_NATS_URL=nats://localhost:4222

CRUD examples (standalone service)

List with filter

curl "http://localhost:20000/api/v1/film?rating=eq.PG&limit=10"

Get by primary key

curl http://localhost:20000/api/v1/film/1

Create

curl -X POST http://localhost:20000/api/v1/film \
  -H "Content-Type: application/json" \
  -d '{"title": "My Film", "rental_rate": 2.99, "rental_duration": 7, "replacement_cost": 14.99, "language_id": 1}'

Full update (PUT)

Replaces the entire row. Any fields not provided are set to their default or NULL.

curl -X PUT http://localhost:20000/api/v1/film/1001 \
  -H "Content-Type: application/json" \
  -d '{"title": "My Film Updated", "rental_rate": 1.99, "rental_duration": 5, "replacement_cost": 14.99, "language_id": 1}'

Partial update (PATCH)

Updates only the fields you provide. Other columns are untouched.

curl -X PATCH http://localhost:20000/api/v1/film/1001 \
  -H "Content-Type: application/json" \
  -d '{"rental_rate": 0.99}'

Delete

curl -X DELETE http://localhost:20000/api/v1/film/1001

Composite primary key

For tables with composite keys (e.g. film_actor with film_id, actor_id):

curl http://localhost:20000/api/v1/film_actor/1,10

OpenAPI (standalone service)

Once running, your full API spec is available at:

  • JSON: http://localhost:20000/api/v1/openapi.json
  • YAML: http://localhost:20000/api/v1/openapi.yaml

Import into Swagger UI, Postman, or Insomnia. Every endpoint, every parameter, every response shape is documented automatically from your live schema.

Maven

mvn clean install
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/yourdb
export SPRING_DATASOURCE_USERNAME=youruser
export SPRING_DATASOURCE_PASSWORD=yourpass
mvn spring-boot:run