API Overview¶

This guide provides a high-level overview of the HTTP API exposed by EventSourcingDB. It explains how to access the OpenAPI specification, how authentication works, which content types are supported, and how to interpret streamed responses.

The v1 API Is Deprecated

The v1 API under /api/v1 is deprecated and will be removed with version 2.0. Every response of it says so in a Deprecation header. Use the v2 API under /api/v2 instead.

Base Path¶

All API routes are served under the base path:

/api/v1

OpenAPI Specification¶

The OpenAPI definition of the v2 API is available as JSON at:

http://localhost:3000/api/v2/system/openapi

The definition of the v1 API, which is deprecated and will be removed with version 2.0, remains available as YAML at:

http://localhost:3000/.well-known/openapi

Both are listed in the API catalog at /.well-known/api-catalog, as defined by RFC 9727, which lets tools discover the APIs of a server and their descriptions.

Use these definitions to generate client code, explore the API, or integrate with tools like Postman, Insomnia, or Swagger UI.

Bruno Collection¶

A ready-to-use Bruno collection is available at eventsourcingdb-client-bruno, providing all API endpoints with example requests and comprehensive documentation.

Authentication¶

All API routes require a valid API token, except for the /api/v1/ping route. The token must be provided using the Authorization header with the Bearer scheme:

Authorization: Bearer <API_TOKEN>

Requests without a valid token are rejected with HTTP status 401 Unauthorized.

Content Types¶

The API supports two primary response formats. Which format is used depends on the specific endpoint and the nature of the data being returned:

application/json: Used for standard request and response bodies
application/x-ndjson: Used for streaming data such as events, event types, or subjects, to name a few

Understanding NDJSON¶

NDJSON stands for Newline-Delimited JSON. It is a lightweight, line-based format for streaming structured data. Each line in an NDJSON stream is a valid JSON object, and lines are separated by a single newline character (\n).

NDJSON is particularly useful for APIs that need to deliver large volumes of data incrementally, such as logs, events, or search results. Instead of buffering all results and returning them as a single JSON array, the server can start streaming items immediately – improving latency, memory efficiency, and responsiveness.

Unlike traditional JSON, NDJSON allows consumers to begin processing data line by line without waiting for the entire payload. This is especially important when working with large datasets or real-time systems.

NDJSON Responses¶

For routes that support application/x-ndjson, the server streams newline-delimited JSON objects. Each object has the following structure:

{
  "type": "...",
  "payload": { ... }
}

The type field indicates what kind of item is being returned – for example, event, eventType, subject, or error. The payload contains the actual content or metadata. For most items it is an object, but it can be any JSON value: a row of an EventQL query is whatever value the query projects, which may be a number or a string.

Error Handling in Streams¶

When using NDJSON, errors may occur at any point in the stream. Even if the initial HTTP response returned 200 OK, subsequent lines may include error entries. For example:

{
  "type": "error",
  "payload": {
    "error": "..."
  }
}

Most routes wrap the message in an object like this. A backup is the exception: it sends the message as a plain string in the payload.

Clients that consume NDJSON streams should be prepared to handle such errors as part of normal stream processing.