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
| Method | Path | Purpose | Token |
|---|---|---|---|
| GET | /ping | Liveness, answers Pong | none |
| GET | /api/v2/ping | Liveness, answers Pong. Clients use it to detect API v2 | none |
| GET | /api/v2/status | Engine, system, event and storage status | reader |
| POST | /api/v2/commit | Commit events with optional preconditions | writer |
| POST | /api/v2/fetch | Events of a subject and its descendants | reader |
| POST | /api/v2/subscribe | Subscribe to a subject (Server-Sent Events) | reader |
| POST | /api/v2/query | Run a GDBQL query | reader |
| GET | /api/v2/subjects | Top level subjects | reader |
| GET | /api/v2/types | Event types | reader |
| GET | /api/v2/schemas | List event schemas | reader |
| POST | /api/v2/schemas | Register an event schema | administrator |
| GET | /api/v2/admin/audit | Verify the hash chain | administrator |
| GET | /api/v2/admin/backup | Export a backup | administrator |
| POST | /api/v2/admin/restore | Restore a backup into an empty store | administrator |
| POST | /api/v2/admin/erase | Erase reference payloads of a subject | administrator |
| POST | /api/v2/admin/index | Rebuild all indexes | administrator |
Commit
{
"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" } }
]
}subjectstarts with/. A single segment such as/customergets a generated ID appended.datais a JSON object of up to about 64 KB.options.storeDataAsReferencestores 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
{
"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.
lowerBoundskips every event before that ID,upperBoundstops at it. The bound events are only included with the matchinginclude…flag.- A
lowerBoundthat does not occur below the subject yields an empty result, not an error. latestByEventTypereturns only the newest event of that type.
Subscribe
{ "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
{ "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
{
"type": "io.genesisdb.app.customer-added",
"schema": {
"type": "object",
"properties": { "name": { "type": "string" } },
"required": ["name"]
}
}See Schema Validation for the supported subset.
Erase
{ "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
{
"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
| Code | Meaning |
|---|---|
400 | Invalid request, schema violation or invalid backup |
401 | Missing or wrong token |
403 | Valid token without permission |
404 | No events for the subject (erase) |
408 | Request cancelled or deadline reached |
409 | Restore into a store that is not empty, or a schema that already exists |
412 | A precondition failed |
413 | Request body exceeds a configured cap |
422 | Read selection exceeds a configured cap, or erase of a subject with only inline data |
429 | More active requests than the configured cap |
503 | The 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.