API reference

#API reference

This section documents every public REST endpoint in EmuView. All endpoints use JSON for request and response bodies, and follow a consistent error envelope format.

#Base URL and versioning

All API requests use your EmuView deployment URL with the /api/v1/ prefix:

https://your-api.example.com/api/v1/collections/...
https://your-api.example.com/api/v1/files/...
https://your-api.example.com/api/v1/automate/...

An unversioned alias (/api/) still resolves to the same handlers, but it is deprecated (ADR 0005): it answers with a Deprecation header and a Link naming its versioned successor, and it will be removed. Use /api/v1/.

#Authentication

All endpoints (except auth and public routes) require a Bearer token:

Authorization: Bearer sk-your-api-key
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

#Request lifecycle

Every request passes through the same middleware pipeline before reaching its handler. Auth failures return 401, permission failures return 403, and both use the standard error envelope:

flowchart LR
    Req["Request<br>/api/v1/..."] --> Auth["Auth middleware<br>session or API key"]
    Auth --> RL["Rate limit"]
    RL --> RBAC["RBAC check<br>role permissions"]
    RBAC --> Handler["Route handler"]
    Handler --> OK["{ data: ... }"]
    Auth -.->|invalid token| Err["{ error, message }"]
    RBAC -.->|denied| Err

The auth middleware resolves the Bearer token to a user identity — see authentication for how sessions and API keys work. RBAC checks compare the user's role permissions against the resource, applying row- and column-level rules from access control.

#Response format

Success (single item):

{ "data": { "id": "...", "title": "..." } }

Success (paginated list):

{ "data": [...], "total": 42, "page": 1, "limit": 25, "hasMore": true }

Error:

{ "error": "not_found", "message": "Resource not found.", "details": {} }

#Response headers

Every response includes:

Header	Description
X-API-Version	Always v1
X-Request-ID	Unique request identifier (exposed via CORS)

#Endpoint groups

Group	Base path	Description
Collections (schema)	/api/v1/collections	Create, read, update, delete collection schemas
Records	/api/v1/collections/:name/records	CRUD operations on collection data
Files	/api/v1/files	Upload, download, list, and delete files
Auth	/api/auth	Sign up, sign in, sessions, API keys
Real-time	/api/v1/collections/:name/stream	SSE and WebSocket subscriptions
Automation	/api/v1/automate	Flows, runs, scripts, webhooks
System	/api/v1/system	Health, OpenAPI spec, LLM context

#Interactive API docs

EmuView auto-generates an OpenAPI 3.1 spec. Access interactive documentation at:

• OpenAPI spec: GET /api/openapi.json
• Interactive UI: GET /api/docs (Scalar)

#Guides in this section

• Collections — Schema CRUD endpoints
• Records — List, create, read, update, delete records with filtering and pagination
• Files — Upload tokens, downloads, file management
• Auth — Sign-in flows, session management, API keys
• Real-time — SSE streams and WebSocket connections
• Automation — Flows, runs, scripts, webhooks
• Storage connections — External S3-compatible storage for automation flows
• MCP server — Connect external AI tools via the Model Context Protocol
• Blueprints — The endpoints, the document format and the install ledger, in the Blueprints section
• Errors — Complete error code catalog