API Integration

The ASP backend serves live OpenAPI documentation for external system integration, scripting, and API debugging. The complete HTTP API reference is generated by the running backend through Swagger UI / Redoc. This documentation site only maintains entry points, authentication guidance, and realtime protocol notes to avoid duplicating the API reference.

Documentation endpoints

After deployment, use these endpoints:

Entry point	Path	Purpose
Swagger UI	/api/docs/	Interactive API documentation with request execution support.
Redoc	/api/redoc/	Read-only API documentation for browsing and searching.
OpenAPI Schema	/api/schema/	OpenAPI 3 schema for SDK generation or third-party tooling.

Authentication

API keys are recommended for automation integrations. Use this request header:

Authorization: Api-Key <key>

Interactive users and frontend login flows can use JWT:

Authorization: Bearer <access_token>

The Swagger UI Authorize dialog supports both authentication methods. Prefer API keys for long-running external integrations because they do not depend on user login sessions and are easier to manage for scripts and service accounts.

API versioning

The main HTTP API currently uses /api/... paths and does not yet have a global /api/v1/... prefix. Agent / CLI integration endpoints use /api/agent/v1/... for automation scenarios that need a more stable contract.

Realtime API

OpenAPI describes HTTP APIs only. Realtime events use WebSocket:

/ws/events/

After a successful connection, the server sends:

{"type": "realtime.connected"}

Clients can send these messages to subscribe to or unsubscribe from comment events:

{"type": "comments.subscribe", "content_type": "case", "object_id": "CASE-000001"}

{"type": "comments.unsubscribe", "content_type": "case", "object_id": "CASE-000001"}

The server may return:

Event type	Description
comments.subscribed	The connection subscribed to comment events for the target record.
comments.unsubscribed	The connection unsubscribed from comment events for the target record.
realtime.error	The message could not be processed or the message type is unknown.

Inbox and comment changes are also pushed through this connection to authenticated users.