Quickstart

Get BunBase running locally in under two minutes.

Prerequisites

Bun 1.2 or later
Git

1. Clone and install

git clone https://github.com/palmcode-ae/bunbase
cd bunbase
bun install

2. Start the dev server

bun dev

The server starts at http://localhost:8080. In development, no .env is needed — sensible defaults are applied automatically.

3. Register a user

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","password":"secret123"}'

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "a3f2...",
  "expires_in": 900,
  "user": { "id": "01JXXX", "email": "alice@example.com" }
}

4. Insert a record

BunBase creates collections and columns on demand — no schema required.

TOKEN="eyJ..."   # access_token from above

curl -X POST http://localhost:8080/api/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"title":"Hello BunBase","published":true,"score":42}'

5. Query with filters

curl "http://localhost:8080/api/v1/posts?filter[published]=true&sort=-score&limit=10" \
  -H "Authorization: Bearer $TOKEN"

6. Upload a file

curl -X POST http://localhost:8080/api/v1/storage/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@photo.jpg"

7. Realtime subscription

const ws = new WebSocket("ws://localhost:8080/realtime");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "auth", token: TOKEN }));
  ws.send(JSON.stringify({ type: "subscribe", channel: "collection:posts" }));
};

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  console.log(msg.event, msg.record);   // "create" { _id: "...", title: "..." }
};

8. Using the TypeScript SDK

import { BunBaseClient } from "@bunbase/js";

const client = new BunBaseClient({ url: "http://localhost:8080" });

await client.auth.login({ email: "alice@example.com", password: "secret123" });

const posts = client.collection("posts");

const post = await posts.create({ title: "Hello", published: true });

const list = await posts.list({
  filter: { published: true },
  sort: "-_created_at",
  limit: 20,
});

const unsub = client.realtime.subscribe("collection:posts", (event) => {
  console.log(event.event, event.record);
});

9. API keys (server-to-server)

API keys let backend scripts authenticate without user sessions. Create one from the SDK or Studio, then use it at the client level:

// Create a key (run once, store securely)
await client.auth.login({ email: "alice@example.com", password: "secret123" });
const { key } = await client.auth.createApiKey("import-script");
// key: "bb_..."

// Use the key in a server-side script
const serverClient = new BunBaseClient({
  url: "http://localhost:8080",
  apiKey: "bb_...",
});

await serverClient.collection("posts").create({ title: "Seeded post" });

Keys never expire and skip the token refresh flow. Revoke them via client.auth.revokeApiKey(id).

Admin API

All admin endpoints require Authorization: Bearer <ADMIN_SECRET>.

In development the default admin secret is dev-admin-secret.

# List all collections
curl http://localhost:8080/api/v1/admin/collections \
  -H "Authorization: Bearer dev-admin-secret"

# Server health + cluster metrics
curl http://localhost:8080/api/v1/admin/health \
  -H "Authorization: Bearer dev-admin-secret"