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.

Base Path¶

All API routes are served under the base path:

/api/v1

OpenAPI Specification¶

The complete OpenAPI definition of the EventSourcingDB API is available at:

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

Use this 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.

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": {
    "message": "..."
  }
}

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