API Reference

Interactive documentation

Clavis provides two interactive API documentation interfaces:

URL	Description
/api/docs	Swagger UI — interactive API explorer
/api/redoc	ReDoc — readable, two-column view

Both are generated from the OpenAPI specification and reflect the actual available endpoints.

Authentication

JWT Bearer (internal users)

For logged-in users (coordinators, creators, admins):

Authorization: Bearer <access_token>

The token is returned on login (POST /api/auth/login).

Cookie auth (participants)

For guests and participants, session cookies are used (set during the join flow). No manual header required.

WebSocket token

For WebSocket connections, a short-lived WS token must first be obtained:

GET /api/auth/ws-token
Authorization: Bearer <access_token>

The WS token is passed as a query parameter.

WebSocket endpoints

Endpoint	Description
GET /api/orgs/{slug}/runs/{run_id}/ws	Coordinator stream: run state updates, team events, feed
GET /api/orgs/{slug}/runs/{run_id}/teams/{team_id}/ws	Team stream: submissions, chat, feed, run state

Connecting

const wsToken = await fetch('/api/auth/ws-token', {
  headers: { Authorization: `Bearer ${accessToken}` }
}).then(r => r.json()).then(d => d.token);

const ws = new WebSocket(
  `wss://app.clavis-rallye.com/api/orgs/${slug}/runs/${runId}/ws?token=${wsToken}`
);

Key endpoints (overview)

Method	Path	Description
POST	/api/auth/login	Login; returns JWT
POST	/api/auth/refresh	Renew token
GET	/api/auth/ws-token	WS token for WebSocket auth
GET	/api/health	Service health status
GET	/api/orgs/{slug}/rallyes	Rallye list
POST	/api/orgs/{slug}/runs	Create a new run
POST	/api/orgs/{slug}/runs/{run_id}/join	Guest join flow
POST	/api/orgs/{slug}/runs/{run_id}/teams/{team_id}/submissions	Create a submission

The complete endpoint list with parameters and response formats is available at /api/docs.

Tenant isolation

All endpoints are isolated by the organization's {slug}. A user can only access resources of their own organization. Cross-tenant access is rejected server-side.