sherbase

Base path /api/sherbase/v1. See API reference for authentication and the api.shebang.pro rewrite.

Every route requires an shb_... key or bearer with base in scope (master keys always qualify). project behaves exactly as described in platform — provisioning a database, and every {slug} route below, is treated as a write for grant purposes (a read grant on another project can list/fetch its databases but not touch one).

The Database envelope below is what list and create return (each other route's response shape is documented in its own section):

{
  "slug": "string",
  "ref": "string (= slug)",
  "status": "ACTIVE_HEALTHY",
  "database": { "host": "string", "port": "number", "version": "string" },
  "api_url": "string | null",
  "publishable_key": "string | null",
  "api_enabled": "boolean"
}

api_url and publishable_key are null together, exactly when api_enabled is false.

GET /api/sherbase/v1/databases

Lists databases.

• Auth — base scope.
• Query params — project (slug, optional).
• Response — 200 { "databases": [Database, ...], "project": "slug" }.
• Errors — 403 insufficient_scope.

POST /api/sherbase/v1/databases

Provisions a new database, then mints its Data API keys and pushes them to the gateway. A Data API key-minting or gateway-push failure never fails the whole call — it's folded into data_api_error on the response and api_enabled is flipped back to false; the database itself is kept and retrying via enable repairs it.

• Auth — base scope, write access to the target project.
• Request body — slug (string, 3–30 lowercase letters/numbers/ underscores, required), project (slug, optional).
• Response — 201 { "project": { ...Database, "secret_key"?, "data_api_error"? }, "project_slug": "string" }. secret_key is shown exactly once, at creation.
• Errors — 400 invalid slug, 403 insufficient_scope, plus whatever mapCreateDatabaseError maps a provisioning failure to (slug already taken, quota reached).

DELETE /api/sherbase/v1/databases/{slug}

Drops a database. Confirm-guarded.

• Auth — base scope, write access to the database's project.
• Path params — slug.
• Request body — confirm (string, required, must equal slug).
• Response — 200 { "ok": true }.
• Errors — 400 (missing/invalid body, or confirm mismatch), 404 not_found, 403 insufficient_scope.

POST /api/sherbase/v1/databases/{slug}/enable

Opts an existing database into the Data API. Idempotent — a second call against an already-enabled, already-keyed database returns the existing publishable key and no secret_key.

• Auth — base scope, write access to the database's project.
• Path params — slug.
• Response — 200 { "slug", "api_url", "publishable_key", "api_enabled", "secret_key"?, "data_api_error"? }.
• Errors — 404 not_found, 403 insufficient_scope.

POST /api/sherbase/v1/databases/{slug}/password

Resets the database's connection password.

• Auth — base scope, write access to the database's project.
• Path params — slug.
• Response — 200 (the new connection details).
• Errors — 404 not_found, 403 insufficient_scope.

POST /api/sherbase/v1/databases/{slug}/query

Runs arbitrary SQL against the database (not restricted to SELECT, so this is a write for grant purposes).

• Auth — base scope, write access to the database's project.
• Path params — slug.
• Request body — sql (string, 1–100,000 chars, required — a single statement; multi-statement bodies are rejected).
• Response — 200 (the query result).
• Errors — 400 (empty/oversized sql, a Postgres error, or the multi-statement guard rejecting the body — surfaced with the underlying message), 404 not_found, 403 insufficient_scope, 500 (a server misconfiguration, e.g. a required environment variable unset).

POST /api/sherbase/v1/databases/{slug}/reload

Reloads the gateway's PostgREST instance for this database, so a schema change made over a direct Postgres connection becomes visible to the Data API without a full restart. A no-op 200 where no gateway is configured.

• Auth — base scope, write access to the database's project.
• Path params — slug.
• Response — 200 { "ok": true }.
• Errors — 404 not_found, 403 insufficient_scope, 409 data_api_disabled (the gateway has no instance registered for this slug — Data API never enabled, or since disabled).

POST /api/sherbase/v1/databases/{slug}/secret

Rotates the database's Data API secret key — the old one stops working immediately.

• Auth — base scope, write access to the database's project.
• Path params — slug.
• Request body — confirm (string, required, must equal slug).
• Response — 200 { "secret_key", "data_api_error"? }. secret_key is shown exactly once.
• Errors — 400 (missing/invalid body, or confirm mismatch), 404 not_found, 400 data_api_not_enabled, 403 insufficient_scope.

Next

agent-login — the device-authorization flow.