> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praeto.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Overview

> Human-readable overview of Praeto Dispatcher API routes.

# API Reference

This is the human-readable API reference. The machine-readable OpenAPI spec is available at:

```text theme={null}
openapi/praeto-dispatcher.openapi.yaml
```

***

## Authentication

Tenant routes:

```http theme={null}
Authorization: Bearer praeto_live_...
```

Admin routes:

```http theme={null}
Authorization: Bearer <ADMIN_API_KEY>
```

***

## Health

### `GET /health`

Returns service and database health.

***

## Admin

### `POST /v1/admin/tenants`

Create or update a tenant.

Request:

```json theme={null}
{
  "tenant_id": "default",
  "tenant_slug": "default"
}
```

***

### `POST /v1/admin/api-keys`

Create a tenant API key.

Request:

```json theme={null}
{
  "tenant_id": "default",
  "name": "production-key"
}
```

Response includes the raw API key once.

***

### `POST /v1/admin/retention/run`

Run retention cleanup.

Request:

```json theme={null}
{
  "apply": false
}
```

Use `apply: true` to delete rows.

***

## Events

### `POST /v1/events`

Publish an event.

Headers:

```http theme={null}
Authorization: Bearer praeto_live_...
Idempotency-Key: invoice-001-created
```

Request:

```json theme={null}
{
  "event_type": "invoice.created",
  "payload": {
    "invoice_id": "inv_001",
    "amount": 4999
  }
}
```

Response:

```json theme={null}
{
  "ok": true,
  "event_id": "...",
  "tenant_id": "default",
  "idempotency_key": "invoice-001-created",
  "endpoint_count": 1,
  "queued_delivery_count": 1,
  "delivery_ids": ["..."]
}
```

***

### `GET /v1/events/{event_id}`

Get event detail.

***

### `GET /v1/events/{event_id}/deliveries`

List deliveries created for an event.

***

## Endpoints

### `GET /v1/endpoints`

List endpoints.

Optional query params:

* `active_only=true`
* `limit=25`
* `offset=0`

***

### `POST /v1/endpoints`

Create endpoint.

Request:

```json theme={null}
{
  "url": "https://example.com/webhook",
  "description": "Production webhook endpoint",
  "subscribed_events": ["invoice.created", "invoice.paid"]
}
```

Response includes `signing_secret` once.

***

### `GET /v1/endpoints/{endpoint_id}`

Get endpoint.

***

### `PATCH /v1/endpoints/{endpoint_id}`

Update endpoint.

Request examples:

```json theme={null}
{
  "is_active": false
}
```

```json theme={null}
{
  "url": "https://example.com/new-webhook",
  "subscribed_events": ["*"]
}
```

***

### `GET /v1/endpoints/{endpoint_id}/health`

Get health summary for an endpoint.

***

### `POST /v1/endpoints/{endpoint_id}/rotate-secret`

Rotate endpoint signing secret with overlap.

***

## Deliveries

### `GET /v1/deliveries`

List deliveries.

Filters:

* `status`
* `endpoint_id`
* `event_type`
* `since`
* `until`
* `limit`
* `offset`

***

### `GET /v1/deliveries/{delivery_id}`

Get delivery detail.

***

### `GET /v1/deliveries/{delivery_id}/attempts`

List delivery attempts.

***

### `POST /v1/deliveries/{delivery_id}/replay`

Replay delivery.

***

## Dead-letter queue

### `GET /v1/dlq`

List dead-lettered deliveries.

***

## Metrics

### `GET /v1/metrics/summary`

Returns operational metrics.

***

## Usage

### `GET /v1/usage/current`

Returns current monthly usage.

***

### `GET /v1/usage/limits`

Returns usage and quota limits.

***

## Safety

### `GET /v1/safety/limits`

Returns safety limits and active protection flags.