Quickstart

Starting EventSourcingDB#

Start EventSourcingDB with the following command. On the first start, Docker downloads the image:

docker run -it -p 3000:3000 \
  thenativeweb/eventsourcingdb run \
  --api-token=secret \
  --data-directory-temporary \
  --http-enabled \
  --https-enabled=false \
  --with-ui

This starts EventSourcingDB on port 3000, with the API token secret, a temporary data directory that is cleaned up on shutdown, unencrypted HTTP, and the management UI.

To verify that EventSourcingDB is running, send a ping:

Changed in 1.3

curl http://localhost:3000/api/v2/system/ping

The response is a small event in an envelope of the type event. If its data holds the message My God, it's full of stars., EventSourcingDB is ready:

{
  "type": "event",
  "data": {
    "specversion": "1.0",
    "id": "01a17256-5112-7c1e-9b4d-3f62a8e05d17",
    "source": "https://www.eventsourcingdb.io",
    "type": "io.eventsourcingdb.api.ping-received",
    "subject": "/api/v2/system/ping",
    "time": "2026-10-25T09:13:41.906512384Z",
    "datacontenttype": "application/json",
    "data": {
      "message": "My God, it's full of stars."
    }
  }
}

Writing an Event#

Changed in 1.3Events are written with a POST request to /api/v2/data/write-events, authenticated with the API token. The following event records that the library acquired a book:

curl \
  -X POST \
  -H "authorization: Bearer secret" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "source": "https://library.eventsourcingdb.io",
        "subject": "/books/42",
        "type": "io.eventsourcingdb.library.book-acquired",
        "data": {
          "title": "2001 – A Space Odyssey",
          "author": "Arthur C. Clarke",
          "isbn": "978-0756906788"
        }
      }
    ]
  }' \
  http://localhost:3000/api/v2/data/write-events

The response is a stream with one JSON item per line. It holds the event as EventSourcingDB stored it, with the fields it sets itself, such as id, time, and hash, and ends with an end item, which says that the stream ended as intended:

{"type":"event","data":{"specversion":"1.0","id":"0","source":"https://library.eventsourcingdb.io","subject":"/books/42","type":"io.eventsourcingdb.library.book-acquired","time":"2026-10-25T09:14:03.218547112Z","predecessorhash":"0000000000000000000000000000000000000000000000000000000000000000","datacontenttype":"application/json","data":{"author":"Arthur C. Clarke","isbn":"978-0756906788","title":"2001 – A Space Odyssey"},"traceparent":null,"tracestate":null,"hash":"esdb:hash:v2:de1500fdb776831195b0c699a15d13142aecd46c5ff48567d0d328fbc4d1ceac","signature":null}}
{"type":"end","data":{}}

Reading the Event#

Changed in 1.3To read the events of the subject /books/42, send a QUERY request to /api/v2/data/read-events. QUERY is the method for reading with a request body:

curl \
  -X QUERY \
  -H "authorization: Bearer secret" \
  -H "content-type: application/json" \
  -d '{
    "subject": "/books/42"
  }' \
  http://localhost:3000/api/v2/data/read-events

The response is the stream you know from writing: the event you have just written, followed by the end item.

Opening the Management UI#

To see the state of the database and run queries, point your browser to http://localhost:3000. For details, see Using the Management UI.

Shutting Down#

Press Ctrl+C to shut down EventSourcingDB. Since the data directory is temporary, the event is gone afterwards.

Next Steps#

• Installing EventSourcingDB covers all ways to install it, including pre-built binaries for macOS, Linux, and Windows.
• Running EventSourcingDB explains how to run it with Docker and as a binary.
• First Steps with EventSourcingDB builds the library example step by step.
• Subjects and Event Types explain the fundamentals behind the example.