# 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](https://www.postman.com/)**, **[Insomnia](https://insomnia.rest/)**, or **[Swagger UI](https://swagger.io/tools/swagger-ui/)**.

## Bruno Collection

A **ready-to-use [Bruno](https://usebruno.com/) collection** is available at [eventsourcingdb-client-bruno](https://github.com/thenativeweb/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**:

```http
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](https://github.com/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**:

```json
{
  "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:

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

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