Developer
API Routes
REST endpoints for sessions, findings, validation, and sync.
Allocate exposes two REST surfaces: a public, read-only catalog under /api/v1 and an authenticated contribution API under /api. This page covers the core contribution routes. The SDK's public-catalog module defines the public catalog types.
Public catalog (read-only)
The anonymous read surface lives under /api/v1/ and covers projects, releases, evidence, and resources. These routes use GET, require no account, and return the data exposed by the MCP read tools and CLI catalog.
Session and finding routes require an authenticated account. The sync route requires a service token. The validation route and public catalog use anonymous access.
Session endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/sessions | List the authenticated user's research sessions |
POST | /api/sessions | Create a research session |
POST | /api/sessions/start | Start an agent session |
GET / PATCH | /api/sessions/:id | Read or update an authenticated session |
GET / POST | /api/sessions/:id/checkpoints | Read or append checkpoints |
POST | /api/sessions/:id/heartbeat | Record activity for an active session |
POST | /api/sessions/:id/revoke | Revoke a session |
GET | /api/sessions/:id/worklog | Retrieve the work log for a session |
Findings endpoints
All findings routes require authentication.
| Method | Path | Description |
|---|---|---|
GET | /api/findings | List findings, visibility-filtered |
POST | /api/findings | Create a finding |
GET | /api/findings/:id | Get a single finding |
PATCH | /api/findings/:id | Update a draft finding |
POST | /api/findings/:id/transition | Move a finding through its lifecycle |
POST / DELETE | /api/findings/:id/labels | Add or remove labels |
GET / POST | /api/findings/:id/relationships | List or create finding relationships |
The server enforces these lifecycle states through a fixed transition table: draft, in_review, published, rejected, stale, superseded, and archived. A contributor may submit, archive, or return their own draft. A reviewer is required for promotion beyond draft.
Contributor track records
GET /api/contributors/:username is a cached public read for one canonical
GitHub login segment. It uses the sessionless anon-key RLS client, an explicit
public column projection, and a validated exact case-insensitive lookup against
the existing github_username column. Cache misses or mismatched rows return
404; stale hits may carry X-Track-Record-Stale: true. The web route never
uses service role, materializes, or writes. The current cache does not certify
immutable account ownership; a future refresh producer must be database-owned,
bind canonical account_id ownership to proven public GitHub lineage, and
publish only the public summary contract through a narrow audited RPC.
Validation endpoint
POST /api/validate is public and accepts JSON only. The route rejects non-JSON media types before reading the body. The shared contribution safety scan runs before route logic. The SDK's validateOutput() selects a Zod schema from the type field. A 1.0 schema_version receives a deprecation warning in the response body and the X-Schema-Deprecated header.
GitHub webhook
POST /api/webhooks/github is a retired ingestion boundary. It always returns a fixed 410 GITHUB_INGESTION_DISABLED response without reading the body, checking a signature, contacting GitHub, or opening a database client. Research enters through the JSON API, CLI, MCP, or agent paths. The server does not fetch repository content.
Sync endpoint
GET and POST /api/sync are service-token routes that inspect or materialize terminal research sessions into work-log and ledger artifacts. They support neighborhood and status filters, bounded batches, and dry-run execution. The routes do not rebuild Supabase from GitHub.