Skip to main content

​
API Reference

This is the human-readable API reference. The machine-readable OpenAPI spec is available at: 
openapi/praeto-dispatcher.openapi.yaml

​
Authentication

Tenant routes: 
Authorization: Bearer praeto_live_...
Admin routes: 
Authorization: Bearer <ADMIN_API_KEY>

​
Health

​
GET /health

Returns service and database health.

​
Admin

​
POST /v1/admin/tenants

Create or update a tenant. Request: 
{
  "tenant_id": "default",
  "tenant_slug": "default"
}

​
POST /v1/admin/api-keys

Create a tenant API key. Request: 
{
  "tenant_id": "default",
  "name": "production-key"
}
Response includes the raw API key once.

​
POST /v1/admin/retention/run

Run retention cleanup. Request: 
{
  "apply": false
}
Use apply: true to delete rows.

​
Events

​
POST /v1/events

Publish an event. Headers: 
Authorization: Bearer praeto_live_...
Idempotency-Key: invoice-001-created
Request: 
{
  "event_type": "invoice.created",
  "payload": {
    "invoice_id": "inv_001",
    "amount": 4999
  }
}
Response: 
{
  "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: 
{
  "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: 
{
  "is_active": false
}

{
  "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.