{ "openapi": "3.0.3", "info": { "title": "rymeDB REST API", "version": "0.1.0", "description": "Operator and data-plane HTTP API for a rymeDB node." }, "servers": [ { "url": "http://127.0.0.1:8080" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "node" }, { "name": "dashboard" }, { "name": "kv" }, { "name": "sql" }, { "name": "rest" }, { "name": "auth" }, { "name": "migrate" }, { "name": "index" }, { "name": "branches" }, { "name": "backups" }, { "name": "shards" }, { "name": "cluster" }, { "name": "streams" } ], "paths": { "/health": { "get": { "tags": [ "node" ], "security": [], "responses": { "200": { "description": "ok" } } } }, "/dashboard": { "get": { "tags": [ "node" ], "security": [], "description": "Static admin web UI (no auth on the shell itself; every API call carries the key).", "responses": { "200": { "description": "html admin console" } } } }, "/dashboard/": { "get": { "tags": [ "dashboard" ], "security": [], "description": "Static admin web UI at its slash-terminated URL.", "responses": { "200": { "description": "html admin console" } } } }, "/dashboard/{path}": { "get": { "tags": [ "dashboard" ], "security": [], "description": "Static dashboard asset path; the server route accepts nested asset paths.", "parameters": [ { "name": "path", "in": "path", "required": true, "description": "Dashboard asset path, including nested path segments when needed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dashboard asset bytes with a content type selected from its extension." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/dashboard/setup": { "get": { "tags": [ "dashboard" ], "security": [], "description": "Reports whether the first dashboard administrator still needs to be created.", "responses": { "200": { "description": "Dashboard bootstrap state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardSetup" } } } } } } }, "/v1/dashboard/bootstrap": { "post": { "tags": [ "dashboard" ], "security": [], "description": "Creates the first platform administrator only; subsequent attempts conflict. Unauthenticated requests are permitted only from loopback client addresses. Other clients must authenticate as a platform superuser using bearer or x-api-key credentials.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardBootstrapRequest" } } } }, "responses": { "201": { "description": "First administrator created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardBootstrapResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/ready": { "get": { "tags": [ "node" ], "security": [], "responses": { "200": { "description": "readiness plus leadership view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ready" } } } } } } }, "/metrics": { "get": { "tags": [ "node" ], "responses": { "200": { "description": "latency histogram, HTTP error counters, and node counters; platform superuser required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metrics" } } } } } } }, "/metrics/prometheus": { "get": { "tags": [ "node" ], "responses": { "200": { "description": "prometheus text exposition; platform superuser required" } } } }, "/v1/audit": { "get": { "tags": [ "node" ], "description": "Recent persisted authentication and administrative actions, including privileged SQL statements over HTTP and the PostgreSQL wire protocol. Only a platform superuser may read the audit trail.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 512 }, "description": "newest events to return, default 100" } ], "responses": { "200": { "description": "newest audit events first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLog" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/observe/slow": { "get": { "tags": [ "node" ], "description": "Recent slow operations (over 5ms) newest-first with kind, fingerprint, table, micros and unix timestamp. Only fingerprints are stored, never raw statements.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "max entries, default 100" }, { "in": "query", "name": "table", "schema": { "type": "string" }, "description": "only entries for this table" } ], "responses": { "200": { "description": "slow entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlowLog" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/traces": { "get": { "tags": [ "node" ], "description": "Recent request spans newest-first with trace/span ids, name, timing and attributes. Backed by the in-memory trace collector fed by the kv/sql/copy handlers.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "max spans, default 100" }, { "in": "query", "name": "name", "schema": { "type": "string" }, "description": "only spans with this operation name" }, { "in": "query", "name": "table", "schema": { "type": "string" }, "description": "only spans carrying this table attribute" } ], "responses": { "200": { "description": "trace spans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/metering": { "get": { "tags": [ "node" ], "responses": { "200": { "description": "idempotent usage aggregates" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/billing/summary": { "get": { "tags": [ "node" ], "description": "Per-tenant usage rollup for downstream invoicing. Aggregation is idempotent; billing outages never block the data path.", "responses": { "200": { "description": "tenant bills", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/billing/invoice": { "get": { "tags": [ "node" ], "description": "Priced invoice for one tenant in micro-USD. Non-owners may only invoice their own tenant. Feed lines to Stripe; rymeDB never calls Stripe from the data path.", "parameters": [ { "name": "tenant", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "invoice with line items and micro-USD total", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/autoscale": { "get": { "tags": [ "node" ], "security": [], "responses": { "200": { "description": "autoscale pressure advice" } } } }, "/v1/qos": { "get": { "tags": [ "node" ], "responses": { "200": { "description": "per-tenant QoS tiers and usage" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/qos/tier": { "post": { "tags": [ "node" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QosTierRequest" } } } }, "responses": { "200": { "description": "tier updated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/migrate/supabase": { "post": { "tags": [ "migrate" ], "description": "Analyze a Supabase Postgres dump into tables and RLS policies with detected tenant columns.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupabaseAnalyzeRequest" } } } }, "responses": { "200": { "description": "extracted schema plan", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/migrate/neon": { "post": { "tags": [ "migrate" ], "description": "Map a Neon branch list (name/parent/LSN) into rymeDB branch create plans.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeonAnalyzeRequest" } } } }, "responses": { "200": { "description": "branch plans with base commit timestamps", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/migrate/apply": { "post": { "tags": [ "migrate" ], "description": "Execute one write SQL statement on the selected branch and record it in the tenant-and-branch-scoped hash-chained migration ledger. Select a branch with X-Ryme-Branch; read-only statements get 400 and duplicate ids get 409 within that scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrateApplyRequest" } } } }, "responses": { "201": { "description": "recorded ledger entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/migrate/ledger": { "get": { "tags": [ "migrate" ], "description": "The selected tenant and branch migration ledger in apply order with its schema version and chain validity. Select a branch with X-Ryme-Branch.", "responses": { "200": { "description": "ledger state", "content": { "application/json": { "schema": { "type": "object", "required": [ "branch", "entries", "version", "valid" ], "properties": { "branch": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "version": { "type": "integer" }, "valid": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/register": { "post": { "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthRegisterRequest" } } } }, "responses": { "201": { "description": "user registered" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "id already registered; re-registration never overwrites", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/auth/verify": { "post": { "tags": [ "auth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthVerifyRequest" } } } }, "responses": { "200": { "description": "password verification receipt" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/token": { "post": { "tags": [ "auth" ], "security": [], "description": "Verify id/password (plus TOTP code when the account enrolled one) and issue a short-lived access key. The key carries the account tenant and roles and expires after 15 minutes; refresh tokens can obtain a replacement.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenRequest" } } } }, "responses": { "201": { "description": "issued key and tenant", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "tenant", "expires_in" ], "properties": { "key": { "type": "string" }, "tenant": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64", "description": "Access-key lifetime in seconds." }, "refresh_token": { "type": "string", "description": "Rotating refresh token, returned by password-grant login." }, "refresh_token_expires_in": { "type": "integer", "format": "int64", "description": "Refresh-token lifetime in seconds." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/keys": { "get": { "tags": [ "auth" ], "summary": "List named API keys", "description": "Lists key metadata for the authenticated user, or for the authenticated tenant administrator. Key secrets are never returned.", "responses": { "200": { "description": "Named API key metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/NamedApiKey" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "auth" ], "summary": "Create a named API key", "description": "Creates a key with the authenticated principal's permissions. The secret is returned once and expires after 90 days.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } }, "responses": { "201": { "description": "Created API key; secret is returned only in this response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/NamedApiKey" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Bearer secret; store securely, it cannot be retrieved again." } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "auth" ], "description": "Revoke an API key by value. Requires a write-capable principal; the body carries the key so it never appears in access logs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" } } } } } }, "responses": { "200": { "description": "revocation receipt", "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/keys/{id}": { "delete": { "tags": [ "auth" ], "summary": "Revoke a named API key", "description": "Revokes a named key by its non-secret ID. Only the owner or a tenant administrator may revoke it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "revocation receipt", "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/session": { "delete": { "tags": [ "auth" ], "security": [], "description": "Revoke the presented rotating refresh token. Possession of the token is sufficient; the token must be sent in the request body, never in a URL. Repeating a revocation is safe and returns revoked=false.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string", "minLength": 1, "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Session revocation result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked" ], "properties": { "revoked": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/otp/setup": { "post": { "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpSetupRequest" } } } }, "responses": { "200": { "description": "TOTP secret" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/otp/verify": { "post": { "tags": [ "auth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpVerifyRequest" } } } }, "responses": { "200": { "description": "OTP verification receipt" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/passkey/challenge": { "post": { "tags": [ "auth" ], "security": [], "description": "Start a passkey assertion without an API key. The response is identical for known and unknown users; attempts are rate-limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyChallengeRequest" } } } }, "responses": { "200": { "description": "WebAuthn challenge" }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "description": "Authentication challenge rate limit exceeded" } } } }, "/v1/auth/passkey/register": { "post": { "tags": [ "auth" ], "description": "Enroll a P-256 credential for a user. Requires a write-capable principal; the public key must be a valid SEC1 point. No attestation verification in v1 (self-enrollment by an authenticated admin).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyRegisterRequest" } } } }, "responses": { "201": { "description": "enrollment receipt" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/passkey/verify": { "post": { "tags": [ "auth" ], "security": [], "description": "Verify a WebAuthn assertion (rpId hash, user-presence flag, origin allow-list, challenge freshness with one-shot consumption, sign-count monotonicity, ECDSA over authenticatorData and clientData hash) and issue a 15-minute access key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyVerifyRequest" } } } }, "responses": { "201": { "description": "issued key and tenant", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "tenant", "expires_in" ], "properties": { "key": { "type": "string" }, "tenant": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64", "description": "Access-key lifetime in seconds." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/oidc/login": { "post": { "tags": [ "auth" ], "security": [], "description": "Build a provider authorization URL. OIDC token verification accepts HS256 secrets or RS256 keys loaded from a configured JWKS file.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcLoginRequest" } } } }, "responses": { "200": { "description": "authorization URL and state", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/auth/oidc/token": { "post": { "tags": [ "auth" ], "security": [], "description": "Verify a provider ID token and issue a 15-minute access key carrying the identity tenant and roles.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OidcTokenRequest" } } } }, "responses": { "201": { "description": "issued key and tenant", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "tenant", "expires_in" ], "properties": { "key": { "type": "string" }, "tenant": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64", "description": "Access-key lifetime in seconds." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/auth/mask": { "post": { "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaskRequest" } } } }, "responses": { "200": { "description": "column mask updated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/presence/join": { "post": { "tags": [ "streams" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceJoinRequest" } } } }, "responses": { "200": { "description": "member count" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/presence/leave": { "post": { "tags": [ "streams" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceLeaveRequest" } } } }, "responses": { "200": { "description": "removal receipt" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/presence/{channel}/stream": { "get": { "tags": [ "streams" ], "description": "Live tenant-scoped presence WebSocket. The first frame is presence_state with the current members; later frames are join/leave events. A lagged consumer receives a fresh presence_state snapshot.", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api_key", "in": "query", "schema": { "type": "string" } } ], "responses": { "101": { "description": "presence WebSocket upgrade" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/realtime/v1/websocket": { "get": { "tags": [ "streams" ], "description": "Supabase Realtime-compatible Phoenix WebSocket for broadcast, presence, and committed postgres_changes subscriptions. Supports v1 JSON objects and v2 JSON arrays, phx_join, phx_leave, heartbeat, broadcast, presence track/untrack, presence_state, presence_diff, postgres_changes, and system events.", "parameters": [ { "name": "apikey", "in": "query", "schema": { "type": "string" } }, { "name": "vsn", "in": "query", "schema": { "type": "string", "enum": [ "1.0.0", "2.0.0" ] } } ], "responses": { "101": { "description": "Supabase Realtime WebSocket upgrade" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/presence/{channel}": { "get": { "tags": [ "streams" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "live members" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/broadcast": { "post": { "tags": [ "streams" ], "description": "Publish an ephemeral tenant-scoped broadcast. In cluster mode the current leader fans it over the cluster mesh; broadcasts are not replayed after restart.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastRequest" } } } }, "responses": { "200": { "description": "broadcast sequence" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/broadcast/{channel}": { "get": { "tags": [ "streams" ], "description": "Live broadcast subscription for one channel, tenant-scoped like posts. Frames are BroadcastMsg JSON (channel, from, payload, commit_ts, sequence).", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api_key", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "broadcast stream" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/topics/append": { "post": { "tags": [ "streams" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DurableAppendRequest" } } } }, "responses": { "200": { "description": "durable cursor" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/regions": { "get": { "tags": [ "node" ], "security": [], "description": "Region placement and follower status. Followers run read_only and reject mutations with 503; strong cross-region writes are WAN-RTT bound by physics.", "responses": { "200": { "description": "region view", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/topics/read": { "get": { "tags": [ "streams" ], "parameters": [ { "name": "partition", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "from", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "messages from cursor" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/topics/{partition}/stream": { "get": { "tags": [ "streams" ], "description": "Live durable topic WebSocket. Replays retained messages from the optional cursor, then follows committed appends; a cursor gap outside retention closes the stream.", "parameters": [ { "name": "partition", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "from", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "api_key", "in": "query", "schema": { "type": "string" } } ], "responses": { "101": { "description": "durable topic WebSocket upgrade" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/vector/upsert": { "post": { "tags": [ "index" ], "description": "Upsert a dense vector. Exact brute-force cosine search; v1 limits documented in schemas.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VectorUpsertRequest" } } } }, "responses": { "200": { "description": "stored" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/vector/search": { "post": { "tags": [ "index" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VectorSearchRequest" } } } }, "responses": { "200": { "description": "nearest hits by cosine score", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/vector/ann-search": { "post": { "tags": [ "index" ], "description": "Approximate HNSW search. Higher ef trades latency for recall. Defaults to 64; the effective value is clamped to top_k..256. Use 128 for higher recall at increased latency.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnSearchRequest" } } } }, "responses": { "200": { "description": "approximate nearest hits by cosine score", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/vector/{table}/{id}": { "delete": { "tags": [ "index" ], "parameters": [ { "$ref": "#/components/parameters/TableParam" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "removal receipt" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/text/index": { "post": { "tags": [ "index" ], "description": "Index a document for TF-IDF ranked full-text search.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextIndexRequest" } } } }, "responses": { "200": { "description": "indexed term count" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/text/search": { "post": { "tags": [ "index" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextSearchRequest" } } } }, "responses": { "200": { "description": "ranked hits", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/text/{table}/{id}": { "delete": { "tags": [ "index" ], "parameters": [ { "$ref": "#/components/parameters/TableParam" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "removal receipt" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/index/stats": { "get": { "tags": [ "index" ], "description": "Platform-superuser index partition layout and estimated process-wide and per-tenant index memory usage. Writes hash-route by id; reads fan out and merge.", "responses": { "200": { "description": "partition layout and estimated index memory budgets", "content": { "application/json": { "schema": { "type": "object", "required": [ "partitions", "spaces", "memory" ], "properties": { "partitions": { "type": "integer" }, "spaces": { "type": "array", "items": { "type": "string" } }, "memory": { "type": "object", "required": [ "full_text", "vector", "per_tenant" ], "properties": { "full_text": { "$ref": "#/components/schemas/IndexMemoryBudget" }, "vector": { "$ref": "#/components/schemas/IndexMemoryBudget" }, "per_tenant": { "type": "array", "items": { "type": "object", "required": [ "tenant", "full_text", "vector" ], "properties": { "tenant": { "type": "string" }, "full_text": { "$ref": "#/components/schemas/IndexMemoryBudget" }, "vector": { "$ref": "#/components/schemas/IndexMemoryBudget" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/kv/{table}/{key}": { "get": { "tags": [ "kv" ], "description": "Fetch a raw value. The response body is the stored bytes.", "parameters": [ { "$ref": "#/components/parameters/TableParam" }, { "$ref": "#/components/parameters/KeyParam" } ], "responses": { "200": { "description": "value bytes" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "kv" ], "description": "Store a raw value. The request body is the value bytes.", "parameters": [ { "$ref": "#/components/parameters/TableParam" }, { "$ref": "#/components/parameters/KeyParam" }, { "name": "ttl", "in": "query", "description": "expiry in seconds", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "commit receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitReceipt" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "kv" ], "parameters": [ { "$ref": "#/components/parameters/TableParam" }, { "$ref": "#/components/parameters/KeyParam" } ], "responses": { "200": { "description": "commit receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitReceipt" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/kv/{table}/{key}/ttl": { "get": { "tags": [ "kv" ], "description": "Remaining TTL in seconds, or -1 when the key never expires.", "parameters": [ { "$ref": "#/components/parameters/TableParam" }, { "$ref": "#/components/parameters/KeyParam" } ], "responses": { "200": { "description": "ttl", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KvTtl" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/sql": { "post": { "tags": [ "sql" ], "description": "Execute one statement in the KEY/VALUE dialect, for example INSERT INTO docs KEY 'k' VALUE 'v' or SELECT * FROM docs KEY 'k'.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SqlRequest" } } } }, "responses": { "200": { "description": "ok, single row, or row set depending on the statement", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SqlOk" }, { "$ref": "#/components/schemas/SqlRow" }, { "$ref": "#/components/schemas/SqlRows" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/sql/copy": { "post": { "tags": [ "sql" ], "description": "Bulk ingest up to 10000 rows in 500-row transactions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyRequest" } } } }, "responses": { "200": { "description": "ingest receipt" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/sql/explain": { "post": { "tags": [ "sql" ], "description": "Return the planned access path without executing writes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SqlRequest" } } } }, "responses": { "200": { "description": "plan" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/rest/v1/{table}": { "get": { "tags": [ "rest" ], "description": "Supabase-style list with select, PostgREST filters including or/and groups, order, limit, offset.", "parameters": [ { "$ref": "#/components/parameters/TableParam" }, { "name": "select", "in": "query", "description": "comma-separated fields to project; aliases use alias:field", "schema": { "type": "string" } }, { "name": "key", "in": "query", "description": "PostgREST filter, for example eq.k1", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "comma-separated field.asc/field.desc clauses with optional nullsfirst/nullslast (key is the default field)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "rows as JSON objects; Prefer count=exact adds Content-Range" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "rest" ], "description": "Insert key/value rows, a JSON object or array with an id/key field, and resolve duplicates with on_conflict=.", "parameters": [ { "$ref": "#/components/parameters/TableParam" } ], "responses": { "201": { "description": "created rows" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "patch": { "tags": [ "rest" ], "description": "Upsert key/value rows or partially update JSON object rows selected by PostgREST filters.", "parameters": [ { "$ref": "#/components/parameters/TableParam" } ], "responses": { "201": { "description": "upserted rows" }, "200": { "description": "updated rows" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "rest" ], "description": "Delete rows selected by a PostgREST filter such as id=eq. or key=eq..", "parameters": [ { "$ref": "#/components/parameters/TableParam" } ], "responses": { "200": { "description": "commit receipt" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/graphql": { "post": { "tags": [ "rest" ], "description": "Minimal GraphQL with table(key:) or table(limit:) selection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphqlRequest" } } } }, "responses": { "200": { "description": "data envelope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/scan/{table}": { "get": { "tags": [ "sql" ], "parameters": [ { "$ref": "#/components/parameters/TableParam" }, { "name": "limit", "in": "query", "description": "max rows, default 100, capped at 1000", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SqlRows" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/branches": { "get": { "tags": [ "branches" ], "responses": { "200": { "description": "all branches sorted by id", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "branches" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchRequest" } } } }, "responses": { "200": { "description": "created; branch parents must be main", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkReceipt" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/branches/{id}": { "get": { "tags": [ "branches" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "branch record with id, parent_id, base_commit_ts, manifest_id and schema_version", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "branches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "deleted, reporting reclaimed garbage rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "garbage": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/branches/{id}/reset": { "post": { "tags": [ "branches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchResetRequest" } } } }, "responses": { "200": { "description": "branch with moved base commit", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/branches/{id}/promote": { "post": { "tags": [ "branches" ], "description": "Swap a child branch into its parent slot and bump schema version.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "promoted parent branch record", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/branches/{id}/diff": { "get": { "tags": [ "branches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "against", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "segment sets unique to each side", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/backups/checkpoint": { "post": { "tags": [ "backups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointRequest" } } } }, "responses": { "200": { "description": "checkpoint record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/backups/latest": { "get": { "tags": [ "backups" ], "security": [], "responses": { "200": { "description": "newest checkpoint manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkpoint" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/backups/pitr": { "get": { "tags": [ "backups" ], "security": [], "parameters": [ { "name": "target", "in": "query", "required": true, "description": "unix timestamp to cover", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "checkpoint covering the target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkpoint" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/snapshots": { "post": { "tags": [ "backups" ], "description": "Snapshot backend files. Returns the max commit plus file names.", "responses": { "200": { "description": "snapshot receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotReceipt" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/backups/restore": { "post": { "tags": [ "backups" ], "description": "Restore to a timestamp. Unavailable in cluster mode.", "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "replay counts per shard", "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "integer" }, "replayed": { "type": "array", "items": { "type": "integer" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/backups/archive": { "post": { "tags": [ "backups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveRequest" } } } }, "responses": { "200": { "description": "archive manifest", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/backups/archives": { "get": { "tags": [ "backups" ], "responses": { "200": { "description": "archive manifests", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/backups/copy": { "post": { "tags": [ "backups" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "backup_id" ], "properties": { "backup_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "copied archive manifest", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/backups/verify": { "get": { "tags": [ "backups" ], "description": "Restore drill without disk writes. Verifies manifest sha256 plus envelope decryption per file.", "parameters": [ { "name": "backup_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "verified file count and commit", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/backups/drill": { "get": { "tags": [ "backups" ], "description": "Latest scheduled restore-drill report. 404 until the first drill completes.", "responses": { "200": { "description": "drill report with backup id, verified file count, timestamp and optional error", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/shards": { "get": { "tags": [ "shards" ], "description": "Layout varies by mode: single returns {mode, shards}; sharded adds a placement list with per-table shard and bytes; hybrid returns {mode, placement} with per-table tier.", "responses": { "200": { "description": "layout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShardLayout" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/shards/move": { "post": { "tags": [ "shards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveShardRequest" } } } }, "responses": { "200": { "description": "move report with table, from, to, bytes and commit", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/ranges": { "get": { "tags": [ "ranges" ], "description": "List placement ranges, or look up the owning range with ?key=. Ranges carry leader and epoch; splits and merges bump epochs.", "parameters": [ { "in": "query", "name": "key", "schema": { "type": "string" }, "description": "UTF-8 key text to route to its owning range" } ], "responses": { "200": { "description": "range list, or a single range for ?key=", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RangeList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/ranges/loads": { "get": { "tags": [ "ranges" ], "description": "Per-range counted write load driving auto-split: id, epoch and writes since the range was created (splits and merges reset children to zero).", "responses": { "200": { "description": "write load per range", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RangeLoad" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/ranges/split": { "post": { "tags": [ "ranges" ], "description": "Split a range at mid into left_id and right_id. Requires expected_epoch to match: stale callers get 409 with the current epoch so they can re-read placement and retry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitRangeRequest" } } } }, "responses": { "200": { "description": "the two child ranges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RangeList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/ranges/merge": { "post": { "tags": [ "ranges" ], "description": "Merge two adjacent same-leader ranges into merged_id. Both expected epochs must match; stale callers get 409.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRangesRequest" } } } }, "responses": { "200": { "description": "the merged range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacementRange" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/ranges/autosplit": { "post": { "tags": [ "ranges" ], "description": "Split every range whose counted REST write load reaches min_writes (defaults to autosplit_writes). Splits use the key-space midpoint with epoch fencing; unsplittable or contended ranges are skipped. Returns the created child range ids.", "parameters": [ { "in": "query", "name": "min_writes", "schema": { "type": "integer" }, "description": "write-load threshold override for this call" } ], "responses": { "200": { "description": "created child range ids, empty when nothing was hot", "content": { "application/json": { "schema": { "type": "object", "properties": { "split": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/ranges/verify": { "post": { "tags": [ "ranges" ], "description": "Compare a range snapshot on the current Raft leader with a member at an expected placement epoch. This is the consistency gate used before a future range transfer; it does not change ownership or data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRangeRequest" } } } }, "responses": { "200": { "description": "source/target row and byte counts plus matching status", "content": { "application/json": { "schema": { "type": "object", "required": [ "range", "epoch", "source", "target", "matching", "ready_for_transfer" ], "properties": { "range": { "type": "string" }, "epoch": { "type": "integer" }, "source": { "type": "integer" }, "target": { "type": "integer" }, "snapshot_ts": { "type": "integer" }, "source_commit": { "type": "integer" }, "target_commit": { "type": "integer" }, "source_rows": { "type": "integer" }, "target_rows": { "type": "integer" }, "source_bytes": { "type": "integer" }, "target_bytes": { "type": "integer" }, "source_truncated": { "type": "boolean" }, "target_truncated": { "type": "boolean" }, "matching": { "type": "boolean" }, "ready_for_transfer": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/ranges/transfer": { "post": { "tags": [ "ranges" ], "description": "Install a consistent range snapshot on a Raft member, verify it at the same commit timestamp, and move the logical range leader with an epoch bump. Current replicated copies remain until range-local storage filtering is enabled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRangeRequest" } } } }, "responses": { "200": { "description": "verified range transfer report", "content": { "application/json": { "schema": { "type": "object", "required": [ "range", "epoch", "leader", "target", "rows", "bytes", "verified" ], "properties": { "range": { "type": "string" }, "epoch": { "type": "integer" }, "leader": { "type": "string" }, "target": { "type": "integer" }, "rows": { "type": "integer" }, "bytes": { "type": "integer" }, "snapshot_ts": { "type": "integer" }, "verified": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/cluster/members": { "get": { "tags": [ "cluster" ], "description": "Raft term, local leadership, commit index, membership and joint config; standalone nodes return mode=standalone, term 0 and an empty member list.", "responses": { "200": { "description": "cluster status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "cluster" ], "description": "Admit a member with log catch-up followed by a joint-consensus transition. Send to the leader.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterMemberRequest" } } } }, "responses": { "200": { "description": "admitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkReceipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/cluster/members/{id}": { "delete": { "tags": [ "cluster" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkReceipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/cluster/transfer": { "post": { "tags": [ "cluster" ], "description": "Hand leadership to another member. Send to the leader.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterTransferRequest" } } } }, "responses": { "200": { "description": "transfer started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkReceipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/cluster/replace": { "post": { "tags": [ "cluster" ], "description": "Swap the member set in one joint-consensus transition. Send to the leader.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterReplaceRequest" } } } }, "responses": { "200": { "description": "replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkReceipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/stream": { "get": { "tags": [ "streams" ], "parameters": [ { "name": "table", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "api_key", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "exclusive commit watermark; replays retained changes after it, then continues live without duplicates" } ], "responses": { "200": { "description": "change stream" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/query-stream": { "get": { "tags": [ "streams" ], "description": "Opens a live query stream. In addition to table, limit, and branch, PostgREST-style select/order controls and field filter query parameters such as status=eq.ready are supported.", "parameters": [ { "name": "table", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "branch", "in": "query", "schema": { "type": "string" } }, { "name": "select", "in": "query", "schema": { "type": "string" }, "description": "comma-separated JSON fields to project in reactive query rows" }, { "name": "order", "in": "query", "schema": { "type": "string" }, "description": "PostgREST-style order expression, for example created_at.desc" }, { "name": "api_key", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "live query stream" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "parameters": { "TableParam": { "name": "table", "in": "path", "required": true, "schema": { "type": "string" } }, "KeyParam": { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "invalid argument", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "valid credentials without the required permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "unknown row, branch or checkpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "stale epoch or duplicate id; retry against current placement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "operation not available in this mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "NamedApiKey": { "type": "object", "required": [ "id", "name", "created_at", "expires_at" ], "properties": { "id": { "type": "string", "description": "Stable non-secret key identifier; never accepted as a credential." }, "name": { "type": "string" }, "created_at": { "type": "integer", "format": "int64" }, "expires_at": { "type": [ "integer", "null" ], "format": "int64" } } }, "IndexMemoryBudget": { "type": "object", "required": [ "used_bytes", "limit_bytes" ], "properties": { "used_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "limit_bytes": { "type": "integer", "format": "int64", "minimum": 0 } } }, "DashboardSetup": { "type": "object", "required": [ "needs_setup" ], "properties": { "needs_setup": { "type": "boolean", "description": "True only while no dashboard administrator has been registered." } } }, "DashboardBootstrapRequest": { "type": "object", "required": [ "id", "password" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "format": "password", "minLength": 8, "maxLength": 256 } } }, "DashboardBootstrapResponse": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "OkReceipt": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "CommitReceipt": { "type": "object", "required": [ "commit" ], "properties": { "commit": { "type": "integer" } } }, "Ready": { "type": "object", "properties": { "ready": { "type": "boolean" }, "node": { "type": "string" }, "commit": { "type": "integer" }, "leader": { "type": "boolean" }, "cluster": { "type": "boolean" } } }, "SlowLog": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "type": "object", "required": [ "kind", "fingerprint", "table", "micros", "at_unix" ], "properties": { "kind": { "type": "string" }, "fingerprint": { "type": "string" }, "table": { "type": "string" }, "micros": { "type": "integer" }, "at_unix": { "type": "integer" } } } } } }, "TraceList": { "type": "object", "required": [ "spans" ], "properties": { "spans": { "type": "array", "items": { "type": "object", "required": [ "trace_id", "span_id", "name", "started_unix", "duration_micros", "attributes" ], "properties": { "trace_id": { "type": "string" }, "span_id": { "type": "string" }, "parent": { "type": "string" }, "name": { "type": "string" }, "started_unix": { "type": "integer" }, "duration_micros": { "type": "integer" }, "attributes": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } } } } } }, "Metrics": { "type": "object", "properties": { "node": { "type": "string" }, "uptime_secs": { "type": "integer" }, "commit": { "type": "integer" }, "rest_count": { "type": "integer" }, "rest_mean_micros": { "type": "number" }, "rest_max_micros": { "type": "integer" }, "http_request_count": { "type": "integer", "description": "HTTP requests since server start." }, "http_4xx_count": { "type": "integer", "description": "HTTP 4xx responses since server start." }, "http_5xx_count": { "type": "integer", "description": "HTTP 5xx responses since server start." }, "p50_micros": { "type": "integer" }, "p90_micros": { "type": "integer" }, "p95_micros": { "type": "integer" }, "p99_micros": { "type": "integer" }, "p999_micros": { "type": "integer" } } }, "AuditLog": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } } }, "AuditEvent": { "type": "object", "required": [ "timestamp_secs", "method", "action", "status", "outcome" ], "properties": { "timestamp_secs": { "type": "integer" }, "actor": { "type": "string", "nullable": true, "description": "authenticated principal ID, or null for unauthenticated attempts" }, "tenant": { "type": "string", "nullable": true, "description": "authenticated principal tenant, or null when no principal tenant is available" }, "method": { "type": "string", "description": "HTTP method, or PG for PostgreSQL wire protocol events" }, "action": { "type": "string", "description": "matched route template or privileged SQL statement class; raw SQL, request bodies, and credentials are never recorded" }, "status": { "type": "integer" }, "outcome": { "type": "string", "enum": [ "success", "failure" ] } } }, "CopyRequest": { "type": "object", "required": [ "table", "rows" ], "properties": { "table": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } } } }, "GraphqlRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" } } }, "QosTierRequest": { "type": "object", "required": [ "tenant", "tier" ], "properties": { "tenant": { "type": "string" }, "tier": { "type": "string", "enum": [ "shared", "dedicated_shard", "dedicated_cluster" ] } } }, "AuthRegisterRequest": { "type": "object", "required": [ "id", "password" ], "properties": { "id": { "type": "string" }, "tenant": { "type": "string" }, "password": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } } } }, "AuthVerifyRequest": { "type": "object", "required": [ "id", "password" ], "properties": { "id": { "type": "string" }, "password": { "type": "string" } } }, "AuthTokenRequest": { "type": "object", "properties": { "id": { "type": "string" }, "password": { "type": "string" }, "code": { "type": "string", "description": "TOTP code, required when the account enrolled one" }, "grant_type": { "type": "string", "enum": [ "password", "refresh_token" ], "default": "password" }, "refresh_token": { "type": "string", "description": "Required when grant_type is refresh_token." } } }, "OtpSetupRequest": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } }, "OtpVerifyRequest": { "type": "object", "required": [ "id", "code" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" } } }, "PasskeyChallengeRequest": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string" } } }, "PasskeyRegisterRequest": { "type": "object", "required": [ "user", "credential_id", "public_key" ], "properties": { "user": { "type": "string" }, "credential_id": { "type": "string" }, "public_key": { "type": "string", "description": "base64url SEC1-encoded P-256 public key" } } }, "PasskeyVerifyRequest": { "type": "object", "required": [ "user", "credential_id", "authenticator_data", "client_data_json", "signature" ], "properties": { "user": { "type": "string" }, "credential_id": { "type": "string" }, "authenticator_data": { "type": "string", "description": "base64url authenticator data" }, "client_data_json": { "type": "string", "description": "base64url client data JSON" }, "signature": { "type": "string", "description": "base64url DER ECDSA signature" } } }, "OidcLoginRequest": { "type": "object", "required": [ "redirect_uri" ], "properties": { "redirect_uri": { "type": "string" }, "state": { "type": "string" } } }, "OidcTokenRequest": { "type": "object", "required": [ "id_token" ], "properties": { "id_token": { "type": "string" } } }, "SupabaseAnalyzeRequest": { "type": "object", "required": [ "dump" ], "properties": { "dump": { "type": "string" } } }, "NeonAnalyzeRequest": { "type": "object", "required": [ "branches" ], "properties": { "branches": { "type": "string" } } }, "MigrateApplyRequest": { "type": "object", "required": [ "id", "sql" ], "properties": { "id": { "type": "string" }, "sql": { "type": "string" }, "author": { "type": "string" } } }, "LedgerEntry": { "type": "object", "required": [ "migration_id", "checksum", "parent_checksum", "applied_unix", "result_schema_version", "author" ], "properties": { "migration_id": { "type": "string" }, "checksum": { "type": "string" }, "parent_checksum": { "type": "string" }, "applied_unix": { "type": "integer" }, "result_schema_version": { "type": "integer" }, "author": { "type": "string" } } }, "MaskRequest": { "type": "object", "required": [ "table", "fields" ], "properties": { "table": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } } }, "PresenceJoinRequest": { "type": "object", "required": [ "channel", "member" ], "properties": { "channel": { "type": "string" }, "member": { "type": "string" }, "state": { "type": "object" }, "ttl_secs": { "type": "integer" } } }, "PresenceLeaveRequest": { "type": "object", "required": [ "channel", "member" ], "properties": { "channel": { "type": "string" }, "member": { "type": "string" } } }, "BroadcastRequest": { "type": "object", "required": [ "channel", "payload" ], "properties": { "channel": { "type": "string" }, "from": { "type": "string" }, "payload": {} } }, "DurableAppendRequest": { "type": "object", "required": [ "partition", "key", "value" ], "properties": { "partition": { "type": "string", "minLength": 1, "maxLength": 256 }, "key": { "type": "string" }, "value": { "type": "string" }, "retention": { "type": "integer" } } }, "VectorUpsertRequest": { "type": "object", "required": [ "table", "id", "vector" ], "properties": { "table": { "type": "string" }, "id": { "type": "string" }, "vector": { "type": "array", "items": { "type": "number" }, "maxItems": 4096 } } }, "VectorSearchRequest": { "type": "object", "required": [ "table", "vector" ], "properties": { "table": { "type": "string" }, "vector": { "type": "array", "items": { "type": "number" }, "maxItems": 4096 }, "top_k": { "type": "integer" } } }, "AnnSearchRequest": { "type": "object", "required": [ "table", "vector" ], "properties": { "table": { "type": "string" }, "vector": { "type": "array", "items": { "type": "number" }, "maxItems": 4096 }, "top_k": { "type": "integer" }, "ef": { "type": "integer", "default": 64 } } }, "TextIndexRequest": { "type": "object", "required": [ "table", "id", "text" ], "properties": { "table": { "type": "string" }, "id": { "type": "string" }, "text": { "type": "string" } } }, "TextSearchRequest": { "type": "object", "required": [ "table", "query" ], "properties": { "table": { "type": "string" }, "query": { "type": "string" }, "top_k": { "type": "integer" } } }, "KvTtl": { "type": "object", "required": [ "ttl" ], "properties": { "ttl": { "type": "integer", "description": "seconds remaining, -1 when persistent" } } }, "SqlRequest": { "type": "object", "required": [ "sql" ], "properties": { "sql": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } } } }, "SqlOk": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "SqlRow": { "type": "object", "properties": { "pk": { "type": "string" }, "value": { "type": "string" } } }, "SqlRows": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/SqlRow" } } } }, "BranchRequest": { "type": "object", "required": [ "id", "parent", "base_commit_ts" ], "properties": { "id": { "type": "string" }, "parent": { "type": "string", "enum": [ "main" ], "description": "Only main is supported as a branch parent." }, "base_commit_ts": { "type": "integer", "minimum": 0, "format": "int64", "description": "Snapshot commit watermark; 0 means current and nonzero values cannot be in the future." } } }, "BranchResetRequest": { "type": "object", "required": [ "base_commit_ts" ], "properties": { "base_commit_ts": { "type": "integer", "minimum": 0, "format": "int64", "description": "Snapshot commit watermark; 0 means current and nonzero values cannot be in the future." } } }, "CheckpointRequest": { "type": "object", "properties": { "manifest_id": { "type": "string" } } }, "Checkpoint": { "type": "object", "properties": { "id": { "type": "string" }, "commit_ts": { "type": "integer" }, "manifest_id": { "type": "string" }, "created_unix": { "type": "integer" } } }, "ArchiveRequest": { "type": "object", "properties": { "backup_id": { "type": "string" } } }, "SnapshotReceipt": { "type": "object", "properties": { "commit": { "type": "integer" }, "files": { "type": "array", "items": { "type": "string" } } } }, "MoveShardRequest": { "type": "object", "required": [ "table" ], "properties": { "tenant": { "type": "string" }, "database": { "type": "string" }, "table": { "type": "string" }, "target": { "type": "integer" } } }, "SplitRangeRequest": { "type": "object", "required": [ "id", "mid", "left_id", "right_id", "expected_epoch" ], "properties": { "id": { "type": "string" }, "mid": { "type": "string" }, "left_id": { "type": "string" }, "right_id": { "type": "string" }, "expected_epoch": { "type": "integer" } } }, "MergeRangesRequest": { "type": "object", "required": [ "left_id", "right_id", "merged_id", "expected_left_epoch", "expected_right_epoch" ], "properties": { "left_id": { "type": "string" }, "right_id": { "type": "string" }, "merged_id": { "type": "string" }, "expected_left_epoch": { "type": "integer" }, "expected_right_epoch": { "type": "integer" } } }, "VerifyRangeRequest": { "type": "object", "required": [ "id", "target", "expected_epoch" ], "properties": { "id": { "type": "string" }, "target": { "type": "integer", "description": "Raft member id to compare against" }, "expected_epoch": { "type": "integer" }, "max_rows": { "type": "integer", "minimum": 1, "maximum": 100000 } } }, "TransferRangeRequest": { "type": "object", "required": [ "id", "target", "expected_epoch" ], "properties": { "id": { "type": "string" }, "target": { "type": "integer", "description": "Raft member id that will receive the range snapshot" }, "expected_epoch": { "type": "integer" }, "max_rows": { "type": "integer", "minimum": 1, "maximum": 100000 } } }, "PlacementRange": { "type": "object", "required": [ "id", "start", "end", "leader", "epoch" ], "properties": { "id": { "type": "string" }, "start": { "type": "array", "items": { "type": "integer" } }, "end": { "type": "array", "items": { "type": "integer" } }, "leader": { "type": "string" }, "epoch": { "type": "integer" } } }, "RangeList": { "type": "array", "items": { "$ref": "#/components/schemas/PlacementRange" } }, "RangeLoad": { "type": "object", "required": [ "id", "epoch", "writes" ], "properties": { "id": { "type": "string" }, "epoch": { "type": "integer" }, "writes": { "type": "integer", "description": "counted REST and wire-gateway writes routed to this range since it was created" } } }, "ShardLayout": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "single", "sharded", "hybrid" ] }, "shards": { "type": "integer" }, "placement": { "type": "array", "items": { "type": "object", "properties": { "tenant": { "type": "string" }, "database": { "type": "string" }, "table": { "type": "string" }, "shard": { "type": "integer" }, "tier": { "type": "string" }, "bytes": { "type": "integer" } } } } } }, "ClusterMemberRequest": { "type": "object", "required": [ "id", "addr" ], "properties": { "id": { "type": "integer" }, "addr": { "type": "string", "example": "127.0.0.1:9000" } } }, "ClusterTransferRequest": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "integer" } } }, "ClusterReplaceRequest": { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterMemberRequest" } } } }, "ClusterMember": { "type": "object", "properties": { "id": { "type": "integer" }, "addr": { "type": "string" }, "self": { "type": "boolean" } } }, "ClusterStatus": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "standalone", "raft" ] }, "term": { "type": "integer" }, "leader": { "type": "boolean" }, "commit": { "type": "integer" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterMember" } }, "joint": { "type": "array", "items": { "type": "integer" } } } } } } }