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.

The MetricStrip (mission control) shows branch health, active sessions, and entry velocity — this is the real component from the dashboard, fed static demo data.

Two APIs, one server

Vinculum exposes two interfaces on the same port. The MCP tool surface (at POST /mcp) is what AI 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 /api/health endpoint is 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 tool surface — with parameter schemas and examples — is covered at MCP Integration.

Rate limits

The server rate-limits writes and reads alike, including MCP tool calls and the dashboard's own requests. Limits count per account once you're signed in, and per IP otherwise. The SSE stream (/api/dashboard/stream), /api/health and /healthz are exempt. Self-hosted installs can change the limits with the VINCULUM_RATE_LIMITS environment variable.

CORS

By default every route answers any origin with Access-Control-Allow-Origin: *, and without credentials. On a self-hosted install, set VINCULUM_CORS_ORIGINS to a comma-separated list of origins: listed origins get their own origin back, with credentials allowed, and any other origin gets no CORS headers.