Skip to main content
The Overlay web app is built on a JSON API under /api/v1. The reference lists the routes that are meant to be called from outside the app. Routes the app uses only for its own screens (onboarding, the Agent Host protocol, title generation and similar) are left out and may change without notice.
For most integrations, MCP is the better starting point: it has self-serve sign-in and covers notes, files, memory, skills and automations. REST API keys are not open to customers yet. See Authentication.

​
Base URL

​
Authentication

Requests from the web app carry its signed, httpOnly session cookie. Programmatic callers send Authorization: Bearer ovl_sk_… with an API key whose scopes cover the route. A request without valid credentials gets 401 and a WWW-Authenticate: Bearer header. Calls that spend credit on someone else’s behalf, such as generation in a paid workspace, may require an Idempotency-Key header so a retried request is not charged twice.

​
Requests

  • GET and DELETE take query parameters. POST, PATCH and PUT take JSON bodies.
  • Uploads use a two-step flow: ask for an upload URL, PUT the file to it, then register the file. See the files guide.
  • Streaming routes (chat replies, run events) answer with server-sent events.
Every request is validated against the same schemas the reference is generated from, so a malformed body is rejected with 400 before it reaches the handler.

​
Errors

JSON errors share one shape:
Some routes add fields, such as the limit that was hit. Common statuses:

​
Guides

Bootstrap

Load the signed-in person, workspace and capabilities.

Conversations

Start chats and stream replies.

Files

Upload, list and read files.

Memory

Search and manage memories.

Automations

Create, test and run automations.

Billing

Read the plan and usage.

​
Reference

The endpoint reference in the sidebar is generated from the API’s own schemas on every docs build, so it always matches the deployed routes.