API Reference

The Kolaybase REST API is available at https://api.kolaybase.com/api. All project-scoped endpoints require either a JWT token or an API key passed via the apikey header.

Authentication Headers

Public REST API (PostgREST-style)

These endpoints use the API key and follow a PostgREST-style query interface. Base path: /api/rest/v1.

Select rows

GET /api/rest/v1/:table?select=*&id=eq.1

Headers:
  apikey: <anon-key>

Query params:
  select    — columns to return (default: *)
  <column>  — filter value: eq.<v>, neq.<v>, gt.<v>, gte.<v>, lt.<v>, lte.<v>, like.<pattern>, ilike.<pattern>, is.null|true|false, in.(a,b,c)
  order     — column.asc or column.desc (comma-separated)
  limit     — max rows
  offset    — skip rows

Insert rows

POST /api/rest/v1/:table
Headers:
  apikey: <service-key>
  Content-Type: application/json
  Prefer: return=representation   # optional

Body: { "column1": "value", "column2": 123 }
  — or array for bulk insert —
Body: [{ "column1": "a" }, { "column1": "b" }]

Update rows

PATCH /api/rest/v1/:table?column=eq.value
Headers:
  apikey: <service-key>
  Content-Type: application/json
  Prefer: return=representation   # optional

Body: { "column1": "new-value" }

Delete rows

DELETE /api/rest/v1/:table?column=eq.value
Headers:
  apikey: <service-key>
  Prefer: return=representation   # optional

SDK Auth Endpoints

Project user authentication. Base path: /api/rest/v1/auth. Requires apikey header.

Sign Up

POST /api/rest/v1/auth/signup
Body: {
  "email": "user@example.com",
  "password": "secret123",
  "firstName": "John",   // optional
  "lastName": "Doe"      // optional
}

Response: { accessToken, refreshToken, expiresIn, user }

Sign In

POST /api/rest/v1/auth/signin
Body: { "email": "user@example.com", "password": "secret123" }

Response: { accessToken, refreshToken, expiresIn, user }

Verify Email

POST /api/rest/v1/auth/verify-email
Body: { "otp": "123456" }

Forgot Password

POST /api/rest/v1/auth/forgot-password
Body: { "email": "user@example.com" }

Reset Password

POST /api/rest/v1/auth/reset-password
Body: { "otp": "123456", "newPassword": "newsecret123" }

Magic Link

POST /api/rest/v1/auth/magic-link
Body: { "email": "user@example.com" }

POST /api/rest/v1/auth/magic-link/verify
Body: { "otp": "123456" }

OAuth

GET /api/rest/v1/auth/signin/:provider?redirect_to=https://myapp.com/callback
  — provider: google, github
  — Returns: { url } — redirect user to this URL

GET /api/rest/v1/auth/callback/:projectId/:provider
  — Keycloak redirects here after OAuth
  — Redirects to your app with tokens in URL hash

Refresh Token

POST /api/rest/v1/auth/refresh
Body: { "refreshToken": "..." }

Response: { accessToken, refreshToken, expiresIn }

Get Current User

GET /api/rest/v1/auth/me
Headers:
  Authorization: Bearer <access-token>

Response: { id, email, username, emailVerified, ... }

Other Auth Endpoints

Project Management

Requires platform JWT. Base path: /api/projects.

Table Management

Requires JWT or API key.

Storage

S3-compatible file storage. Requires JWT or API key.

SQL Execution

POST /api/sql/execute
Headers:
  Authorization: Bearer <jwt>
Body: {
  "projectId": "...",
  "query": "SELECT * FROM users LIMIT 10"
}

Response: { columns: [...], rows: [...], rowCount, duration }