HTTP API

The standalone server exposes one authenticated versioned protocol for metadata, transactions and objects.

On this page

Transport and authentication

All endpoints use the /api/v1 prefix. Non-loopback listeners require TLS 1.3. Trusted clients send Authorization: Bearer <owner credential>. Studio creates an HttpOnly session on the server origin. State-changing session requests follow the server’s origin and CSRF checks.

GET /status and GET /session report connection state. Database access requires authentication; locked storage must be unlocked through the configured authority. Custom users, assignable roles and API permission presets are still delivery work.

Keep connections open

HTTP/1.1 keep-alive is explicitly enabled. Clients should drain each response body and reuse a connection pool. WebSocket adds concurrent correlated transactions on a persistent socket through the same engine.

WebSocket protocol and client →

JSON envelopes

This is the envelope shape, not a request to execute. Unknown fields, duplicate JSON keys, trailing data and excessive structure are rejected. Binary object responses use their own content type and range headers.

json

{ "ok": true, "data": { "revision": "1", "results": [], "replayed": false } }

{ "ok": false, "error": {
  "code": "precondition_failed",
  "message": "The transaction precondition failed.",
  "retryable": false
} }

Download complete JSON Schema

Endpoint inventory

Method	Path	Purpose
GET	/status	Actual mode, lock state and capabilities
GET / POST / DELETE	/session	Inspect, create or revoke the caller session
POST	/unlock	Native {password} or external {} recovery
POST	/lock	Drain admitted operations and lock storage
GET	/database	Instance identity, snapshot counts, storage, limits and workers
GET	/collections	Collection and index inventory
POST	/execute	Atomic operations and receipt replay
GET upgrade	/ws	qirava.v1 persistent transaction protocol
GET / POST	/uploads	Inventory or idempotent upload initiation
GET / DELETE	/uploads/:id	Progress or abort unpublished upload
PUT	/uploads/:id/parts/:index	Upload exact binary part bytes
GET	/objects	Immutable object inventory
GET / HEAD	/objects/:id	Stream download or metadata; one byte range

Request and result schemas

The reference below is generated from qirava-contracts and qirava-engine. Structural schema validation complements runtime authorization, resource admission and domain validation. Required fields come directly from the generated schemas.

Browse transaction operations →

Browse all request/result types →

Handle failures by outcome

Treat outcome_unknown and interrupted write responses as unresolved intent. Recover and retry the exact original request, without changing its ID or operations. Do not infer that an error means no write occurred. A precondition or schema rejection is a definitive rejection; an unavailable storage authority never selects another custody mode.