Logo
Logo

HTTP API

Every route of the GenesisDB HTTP API with request bodies, responses and status codes.

The current API lives under /api/v2. The API of GenesisDB 1.x stays available unchanged under /api/v1, see Upgrade from 1.x. All routes except /ping and /api/v2/ping require Authorization: Bearer <token>. Every administration route lives under /api/v2/admin, so a proxy can restrict it by path. Request bodies are exactly one JSON document in valid UTF-8. List responses are NDJSON, one JSON value per line. Send X-Disable-Ndjson: true to receive a JSON array instead.

Routes

MethodPathPurposeToken
GET/pingLiveness, answers Pongnone
GET/api/v2/pingLiveness, answers Pong. Clients use it to detect API v2none
GET/api/v2/statusEngine, system, event and storage statusreader
POST/api/v2/commitCommit events with optional preconditionswriter
POST/api/v2/fetchEvents of a subject and its descendantsreader
POST/api/v2/subscribeSubscribe to a subject (Server-Sent Events)reader
POST/api/v2/queryRun a GDBQL queryreader
GET/api/v2/subjectsTop level subjectsreader
GET/api/v2/typesEvent typesreader
GET/api/v2/schemasList event schemasreader
POST/api/v2/schemasRegister an event schemaadministrator
GET/api/v2/admin/auditVerify the hash chainadministrator
GET/api/v2/admin/backupExport a backupadministrator
POST/api/v2/admin/restoreRestore a backup into an empty storeadministrator
POST/api/v2/admin/eraseErase reference payloads of a subjectadministrator
POST/api/v2/admin/indexRebuild all indexesadministrator

Commit

json
{
  "events": [
    {
      "source": "io.genesisdb.app",
      "subject": "/customer/42",
      "type": "io.genesisdb.app.customer-added",
      "data": { "name": "Bruce Wayne", "email": "bruce@wayne.enterprises" },
      "options": { "storeDataAsReference": true }
    }
  ],
  "preconditions": [
    { "type": "isSubjectNew", "payload": { "subject": "/customer/42" } }
  ]
}
  • subject starts with /. A single segment such as /customer gets a generated ID appended.
  • data is a JSON object of up to about 64 KB.
  • options.storeDataAsReference stores the payload as an erasable reference payload.
  • All events of a request are published atomically. There is no limit on the number of events per request.

The answer is the stored events as NDJSON, including id, time, hash and predecessorhash. A failed precondition answers 412 with {"type": "...", "message": "..."}.

Fetch

json
{
  "subject": "/customer",
  "options": {
    "lowerBound": "<event id>",
    "includeLowerBoundEvent": true,
    "upperBound": "<event id>",
    "includeUpperBoundEvent": false,
    "latestByEventType": "io.genesisdb.app.customer-added"
  }
}

Returns the events of the subject and all of its descendants in commit order. All options are optional.

  • lowerBound skips every event before that ID, upperBound stops at it. The bound events are only included with the matching include… flag.
  • A lowerBound that does not occur below the subject yields an empty result, not an error.
  • latestByEventType returns only the newest event of that type.

Subscribe

json
{ "subject": "/customer", "interval": 0.5, "options": { "lowerBound": "<event id>" } }

Answers text/event-stream. The existing history comes first, then new events as they are committed, each as data: <event>. When a poll finds nothing new, a heartbeat data: {"payload":""} is sent. interval is the poll interval in seconds, default 1, between 0.1 and 86400.

A subscription whose polls fail five times in a row ends with event: error and data: {"error": "..."} and closes the stream. Treat a closed stream as a reason to reconnect.

Query

json
{ "query": "STREAM e FROM events WHERE e.subject UNDER '/customer' MAP { id: e.id }" }

Answers the rows as NDJSON by default. A query with a single value such as MAP COUNT() answers that value as its only line. With X-Disable-Ndjson: true the answer is one JSON array instead, also for a single value ([3]) and an empty result ([]). /api/v1/query always answers NDJSON, as in 1.1.6. See Query Language.

Subjects and types

GET /api/v2/subjects answers {"subject": "/customer"} per line, GET /api/v2/types answers {"type": "..."} per line.

Schemas

json
{
  "type": "io.genesisdb.app.customer-added",
  "schema": {
    "type": "object",
    "properties": { "name": { "type": "string" } },
    "required": ["name"]
  }
}

See Schema Validation for the supported subset.

Erase

json
{ "subject": "/customer/42" }

Replaces every reference payload of the subject and its descendants with {}. See GDPR and Erasure.

Backup, restore and index

GET /api/v2/admin/backup answers a consistent snapshot, POST /api/v2/admin/restore writes one into an empty store. POST /api/v2/admin/index rebuilds the indexes from the event logs, reads and writes wait meanwhile. See Backup and Restore.

Status

json
{
  "engine": { "version": "2.0.0", "channel": "stable" },
  "events": { "count": 1204, "subjects": 12, "types": 9, "storageSize": 834512 },
  "storage": { "storageFormat": "current", "ready": true },
  "system": { "os": "linux", "arch": "arm64" }
}

Status codes

CodeMeaning
400Invalid request, schema violation or invalid backup
401Missing or wrong token
403Valid token without permission
404No events for the subject (erase)
408Request cancelled or deadline reached
409Restore into a store that is not empty, or a schema that already exists
412A precondition failed
413Request body exceeds a configured cap
422Read selection exceeds a configured cap, or erase of a subject with only inline data
429More active requests than the configured cap
503The store is not ready, for example during an index rebuild

API v1

The API of GenesisDB 1.x is frozen under /api/v1 and answers exactly like 1.1.6, so 1.x clients keep working. Every v1 response carries Deprecation: true and a Link to its v2 successor. The mapping is in Upgrade from 1.x.