API Reference
Developer-facing overview of the main MARCUS API surfaces and the request/response patterns they use.
This is a practical API reference, not an exhaustive schema dump. It is designed to help a developer, technical reviewer, or informatics lead understand how the main parts of MARCUS are exposed over HTTP.
For exact types, use the generated frontend API types and the backend route modules. This page focuses on the main endpoint families, common conventions, and the shape of the workflows they support.
Common Conventions
Base Path
The backend API is exposed under /api. In browser use, the frontend normally reaches it through the same-origin Next.js proxy rather than by calling the backend origin directly.
Required Headers
| Header | Purpose |
|---|---|
Content-Type: application/json | Used for JSON request bodies |
X-CSRF-Token | Required for cookie-authenticated mutating requests |
| Cookie headers | Carry session and refresh state in browser flows |
| Org or context headers | Added by the frontend proxy or request helpers where scoped behavior is needed |
Authentication Model
MARCUS uses:
- cookie-based authentication
- CSRF protection on state-changing requests
- server-side organization and project authorization
This means a client normally authenticates once, stores session cookies, fetches a CSRF token, and includes that token on writes.
Authentication Endpoints
| Method | URL | Purpose | Representative request shape | Representative response shape |
|---|---|---|---|---|
GET | /api/auth/csrf | Bootstrap the CSRF token used for mutating requests | none | { csrf_token } style payload |
POST | /api/auth/login | Sign in with email and password | { email, password } | auth envelope plus cookies |
POST | /api/auth/logout | Clear the current session | empty or minimal JSON | status response |
POST | /api/auth/signup | Create a new account | identity and org fields | auth envelope |
POST | /api/auth/token/refresh | Refresh access session | usually cookie-driven | auth envelope |
GET | /api/auth/sso/providers | List configured SSO providers | none | provider list |
GET | /api/auth/sso/{provider}/authorize | Start an SSO handoff | provider-specific query params | redirect or auth handoff |
GET | /api/auth/sso/{provider}/callback | Complete SSO | provider callback params | auth envelope or redirect outcome |
Project Endpoints
| Method | URL | Purpose | Representative request shape | Representative response shape |
|---|---|---|---|---|
GET | /api/projects | List accessible projects | optional org filters | project list |
POST | /api/projects | Create a project | { title, description?, slug?, kind? } | project record |
GET | /api/projects/{project_id} | Get project detail | none | project detail |
PATCH | /api/projects/{project_id} | Update project metadata | partial project fields | updated project |
DELETE | /api/projects/{project_id} | Delete a project | none | status response |
GET | /api/projects/{project_id}/members | List project members | none | membership list |
GET | /api/projects/{project_id}/invitations | List pending project invitations | none | invitation list |
POST | /api/projects/{project_id}/invitations | Create a project invite | invite email and role payload | invitation record |
Projects are especially important in the API because they define the retrieval boundary for many later operations.
Source And Ingestion Endpoints
| Method | URL | Purpose | Representative request shape | Representative response shape |
|---|---|---|---|---|
GET | /api/projects/{project_id}/sources | List project sources | optional search or filter params | source summaries |
POST | /api/projects/{project_id}/sources/upload | Upload source files or begin upload workflow | multipart form or mediated helper payload | upload receipt or queued ingestion response |
POST | /api/projects/{project_id}/sources/confirm-upload and similar flows | Confirm a previously uploaded asset | upload metadata and storage identifiers | ingestion receipt |
DELETE | /api/projects/{project_id}/sources/{source_id} | Remove a source | none | status response |
POST | /api/projects/{project_id}/sources/{source_id}/retry | Retry failed ingestion | none | retry status |
In practice, the frontend often uses helper utilities rather than hand-writing the exact upload flow. The important idea is that upload is usually a multi-step workflow rather than one simple JSON POST.
Conversation And Chat Endpoints
| Method | URL | Purpose | Representative request shape | Representative response shape |
|---|---|---|---|---|
POST | /api/query/stream | Stream a cited answer over Server-Sent Events | { query, project_id?, conversation_id?, ... } | text/event-stream |
POST | /api/chat/completions | Non-streaming completion path | similar to stream request | JSON answer envelope |
POST | /api/conversations | Create a conversation | { title?, project_id? } | conversation record |
GET | /api/conversations | List conversations | search or filter params | conversation list |
POST | /api/conversations/{conversation_id}/messages | Add a message to a thread | { role, content, ... } | message record or continuation setup |
The two main answer-generation paths are the streaming endpoint and the non-streaming completions endpoint. The streaming endpoint is what powers the live thinking-state and progressive answer rendering in the product.
Streaming Event Types
The stream contract includes event families such as:
statuschunksourcesfollowupsdone
What a status event is for
A status event tells the frontend what stage the backend is in, such as:
- query analysis
- search preparation
- searching
- ranking
- context assembly
- citation preparation
- planning
- composition
These events power the visible "thinking" UI during streaming.
What a chunk event is for
A chunk event carries incremental answer text so the user can see the response as it is being composed.
What a done event is for
A done event closes the answer stream and can carry completion-level metadata such as confidence or final source packaging.
Briefings, Suggestions, And Knowledge-Oriented Endpoints
| Method | URL | Purpose |
|---|---|---|
GET | /api/projects/{project_id}/briefings | List project briefing summaries |
GET | briefing detail helper flows for a source | Fetch one source briefing in detail |
GET | /api/projects/{project_id}/suggestions | Load project-level suggestion chips |
GET | knowledge-page, theme, graph, and matrix helper routes where enabled | Retrieve advanced project analysis data |
The exact route family for advanced knowledge features can vary by feature area, but the high-level pattern stays the same: project-scoped GET and mutation routes for project-level synthesis and comparison tools.
Analytics, Costs, FAQ, And Benchmarks
| Method | URL | Purpose |
|---|---|---|
GET | /api/faq | Read FAQ or public health-adjacent product content |
GET | analytics-related routes | Read organization-level usage data |
GET | /api/admin/costs/summary | Cost summary for authorized admins |
GET | /api/admin/costs/events | Cost event list or stream |
GET | /api/benchmarks/latest | Latest benchmark run |
GET | /api/benchmarks/history | Historical benchmark runs |
These surfaces are mainly for monitoring, administration, and public engineering visibility rather than everyday resident workflow.
Representative Request Pattern For Browser Clients
Most browser clients follow a sequence like this:
- Fetch CSRF token
- Log in and establish cookies
- Call same-origin
/api/...routes through the frontend proxy - Include
X-CSRF-Tokenon state-changing requests - Use SSE for streaming chat responses
This keeps session, CSRF, and origin behavior consistent with the rest of the app.
Notes For Frontend Developers
- The frontend uses a same-origin proxy under
frontend/app/api. - Generated OpenAPI types live in
frontend/src/generated/openapi.ts. - Contract tests for API normalization live under
frontend/tests/api-integration/contracts. - For streaming behavior, the frontend SSE client and thinking-state UI are the most important integration points.
A Practical Caution
If a request "works" in an ad hoc client but does not include the correct cookies, CSRF token, or scope, it may still fail in the real product flow. In MARCUS, the integration contract includes security and scoping behavior, not just endpoint names.