API Reference
Vinculum's REST API — live-rendered from the server's OpenAPI schema. If the interactive explorer below doesn't load, a static endpoint table follows it.
The REST API powers the dashboard — the MetricStrip, Workers panel, and live feed all source from these endpoints.
Two APIs, one server
Vinculum exposes two interfaces on the same port. The MCP tool surface (at POST /mcp) is what Claude sessions use — documented at MCP Integration. This page documents the REST API used by the dashboard and webhook consumers.
Authentication
Web UI endpoints require a valid session JWT, set as an HttpOnly cookie named vinculum_session after sign-in — passkey, a six-digit email code, or Google/GitHub OAuth (Forgejo OAuth is also available on self-hosted installs). The cookie is scoped to the server origin and rotated on each sign-in.
Machine-to-machine endpoints (/api/context/compact, /api/ingest/conversation) accept Authorization: Bearer <token>. Tokens are configured via VINCULUM_INGEST_SECRET and VINCULUM_AUTH_TOKEN_* env vars.
The /healthz and /api/conventions endpoints are public (no auth required).
MCP endpoint
The full MCP tool surface is served at POST /mcp (Streamable HTTP transport). MCP clients negotiate the transport during the initialization handshake. Authentication uses the standard MCP OAuth 2.0 flow: clients are directed to /.well-known/oauth-protected-resource for resource metadata, then through the authorization server at /authorize / /token.
The full, role-filtered tool surface — with parameter schemas and examples — is covered at MCP Integration.
Rate limits
The server applies rate limiting per IP on mutating endpoints. The SSE stream (/api/dashboard/stream) and /healthz are exempt. Self-hosted installs can adjust limits in src/vinculum_mcp/rate_limit.py.
CORS
All custom API routes return Access-Control-Allow-Origin: *. If you need stricter CORS on a self-hosted install, set a reverse proxy rule upstream of the server.