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
| Key | Default | Description |
|---|---|---|
app.allowed-schema | public | PostgreSQL schema to expose |
app.default-page-size | 100 | Rows returned when no limit is specified |
app.max-page-size | 1000 | Maximum rows per request |
server.port | 20000 | HTTP port |
app.nats.enabled | false | Enable CDC real-time subscriptions (SSE + WebSocket) |
app.nats.url | nats://localhost:4222 | NATS server URL (requires JetStream) |
app.nats.stream-name | cdc-stream | NATS 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