API Overview

The Realtime Platform exposes a REST API on the backend server (default port 3000) and a WebSocket gateway via Socket.IO on the same port.

Base URL

http://localhost:3000

All REST endpoints are prefixed with /api/ except health and auth routes.

Authentication

Most API endpoints require authentication via one of:

• JWT Bearer Token — Authorization: Bearer <token> header
• Session Token — Authorization: <session-token> or X-Session-Token: <session-token> header

The Admin UI uses session-based authentication. Service-to-service calls use JWT tokens.

Application Scoping

All entity-owning endpoints are scoped by application. The X-Application-Id header identifies which application's data to access:

curl http://localhost:3000/api/topics \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Application-Id: app_abc123'

The Admin UI auto-attaches this header from the currently selected application.

Environment Scoping

Many endpoints also respect the X-Environment header for environment-specific data:

curl http://localhost:3000/api/schemas/session.status/latest \
  -H 'X-Application-Id: app_abc123' \
  -H 'X-Environment: staging'

Response Format

All API responses return JSON. Successful responses return the resource directly. Errors return:

{
  "error": "NotFoundError",
  "message": "Topic not found: session.status"
}

Common HTTP Status Codes

Health Check

GET /health

Returns {"status":"ok"} — no authentication required.

Metrics

GET /api/metrics/prometheus

Returns Prometheus-format metrics for scraping. No authentication required.

API Sections