Capabilities
Overview
Every public API endpoint is a Capability. Capabilities are declared once in a registry, then automatically exposed as a REST route, an MCP tool, and (where applicable) an OAuth-scoped endpoint. Here is the full matrix.
Why the registry
Alloovium's public API is built around a single source of truth: the capability registry in path. Every capability declares its request model, response model, scopes, rate-limit cost, and transports (REST / MCP / OAuth). Our mount layer then generates the FastAPI route, the FastMCP tool, the OpenAPI entry, and the rate-limit check from that single declaration.
That means the REST docs, the MCP tool list, and the Scalar reference never drift. What you see below is generated from the same data.
Capability matrix
| Capability | Method + Path | Scope | Cost | MCP | OAuth |
|---|---|---|---|---|---|
| vault.list_projects | GET /vault/projects | vault:read | 1 | yes | yes |
| vault.get_project | GET /vault/projects/{id} | vault:read | 1 | yes | yes |
| vault.create_project | POST /vault/projects | vault:write | 2 | yes | no |
| vault.list_documents | GET /vault/documents | vault:read | 1 | yes | yes |
| vault.get_document | GET /vault/documents/{id} | vault:read | 1 | yes | yes |
| vault.upload_document | POST /vault/documents | vault:write | 10 | no (multipart) | no |
| vault.get_ingestion_job | GET /vault/ingestion-jobs/{id} | vault:read | 1 | yes | yes |
| vault.search | POST /vault/search | vault:read | 5 | yes | yes |
| chat.ask | POST /chat | chat:write + vault:read | 10 | yes | no |
| chat.ask_stream | POST /chat/stream | chat:write + vault:read | 10 | no (SSE) | no |
| chat.list_conversations | GET /conversations | chat:read | 1 | yes | yes |
| chat.get_conversation | GET /conversations/{id} | chat:read | 1 | yes | yes |
| templates.start_fill | POST /templates/fill | templates:write | 25 | no (multipart) | no |
| templates.get_fill_status | GET /templates/fill/{id} | templates:read | 1 | yes | yes |
| workflows.list | GET /workflows | workflows:read | 1 | yes | yes |
| workflows.run | POST /workflows/{id}/runs | workflows:write | 25 | yes | no |
| workflows.get_run_status | GET /workflows/runs/{id} | workflows:read | 1 | yes | yes |
| meta.whoami | GET /me | (none) | 1 | yes | yes |
All paths are under /api/v2
All paths are under /api/v2 prefix. Every REST path is really full.Transport matrix
Not every capability accepts every credential or protocol. The rules:
- REST — every capability. Call via
headerwith an API key. - MCP — every non-multipart capability. Multipart uploads (
upload,fill) and SSE streams (stream) are REST-only; MCP clients can't send binary or consume server-sent events over JSON-RPC. - OAuth — read-only capabilities only. Write capabilities require an API key because their handlers need the full ORM principal. Calling a write capability with an OAuth Bearer JWT returns
code.
Browse by group
- Vault — 8 capabilities: projects, documents, upload, ingestion polling, hybrid search.
- Chat — 4 capabilities: ask, list conversations, fetch a conversation.
- Workflows — 3 capabilities: list, run, poll run status.
- Templates — 2 capabilities: start a fill job, poll fill status.
- Meta — 1 capability: whoami.
See also
- Authentication — API keys, OAuth, scopes.
- Rate Limits — how cost maps to the token bucket.
- MCP Server — how to wire these as tools in Claude, ChatGPT, or Cursor.