Reference

Every EventDBX API in one place.

Choose the surface that fits your stack. Each API exposes identical primitives for appending events, inspecting aggregates, and verifying state.

Read the guide Use the CLI

# All APIs expect a bearer token
$ eventdbx token generate --group admin --user jane --expiration 3600

# Export token for reuse
$ export EVENTDBX_TOKEN=eyJhbGciOi...

# Health check
$ curl http://127.0.0.1:7070/health

Authentication

Issue tokens through the CLI and pass them as bearer headers. Tokens are signed JWTs that encode user, group, and expiry.

Headers by surface

REST uses Authorization: Bearer TOKEN.
GraphQL reuses the same header.
gRPC expects authorization: Bearer TOKEN due to lowercase metadata.

REST

Classic HTTP endpoints

Ideal for automation scripts and application backends. Payloads are JSON and follow predictable patterns.

# Append an event
curl -X POST http://127.0.0.1:7070/v1/events \
    -H "Authorization: Bearer ${EVENTDBX_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "aggregate_type": "patient",
        "aggregate_id": "p-002",
        "event_type": "patient-updated",
        "payload": {
            "status": "inactive"
        }
    }'

# Inspect state
curl -H "Authorization: Bearer ${EVENTDBX_TOKEN}" \
    http://127.0.0.1:7070/v1/aggregates/patient/p-002

Key endpoints

POST /v1/events adds an event.
GET /v1/aggregates paginates aggregates.
GET /v1/aggregates/{type}/{id} returns current state.
GET /v1/aggregates/{type}/{id}/events streams timelines.
GET /health reports readiness for orchestration.

GraphQL

Typed queries and mutations

GraphQL is perfect when you need aggregate snapshots and events in a single round trip. The Playground ships with the server for quick iteration.

# Query aggregates
curl -X POST http://127.0.0.1:7070/graphql \
    -H "Authorization: Bearer ${EVENTDBX_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "query": "query Recent($take: Int!) { aggregates(take: $take) { aggregate_type aggregate_id version state } }",
        "variables": { "take": 5 }
    }'

# Append via mutation
curl -X POST http://127.0.0.1:7070/graphql \
    -H "Authorization: Bearer ${EVENTDBX_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "query": "mutation Append($input: AppendEventInput!) { appendEvent(input: $input) { aggregate_type aggregate_id version } }",
        "variables": {
            "input": {
                "aggregate_type": "patient",
                "aggregate_id": "p-002",
                "event_type": "patient-updated",
                "payload": { "status": "inactive" }
            }
        }
    }'

Schema highlights

aggregates query paginates across types.
aggregate query returns state and version for one aggregate.
events field lists timelines inline.
appendEvent mirrors the REST append endpoint.

gRPC

Low latency streaming

Protocol buffers provide strong typing and efficient encoding for multi-language services and workers.

# Append via grpcurl
grpcurl -H "authorization: Bearer ${EVENTDBX_TOKEN}" \
    -d '{
        "aggregate_type": "patient",
        "aggregate_id": "p-002",
        "event_type": "patient-updated",
        "payload_json": "{\"status\":\"inactive\"}"
    }' \
    -plaintext 127.0.0.1:7070 eventdbx.api.EventService/AppendEvent

# Stream events
grpcurl -H "authorization: Bearer ${EVENTDBX_TOKEN}" \
    -d '{ "aggregate_type": "patient", "aggregate_id": "p-002" }' \
    -plaintext 127.0.0.1:7070 eventdbx.api.EventService/ListEvents

Service overview

AppendEvent writes events.
ListAggregates paginates aggregates with Merkle roots.
GetAggregate returns current state.
ListEvents streams timelines.
VerifyAggregate compares Merkle proofs across replicas.