> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> How to call the Overlay Web API and how the generated reference is maintained.

The public web API lives under `/api/v1`. The generated endpoint reference is built from `src/shared/schemas/api-boundary.ts`, which is also used by route boundary validation.

## Base URLs

| Environment | URL                     |
| ----------- | ----------------------- |
| Hosted      | `https://getoverlay.io` |
| Local       | `http://localhost:3000` |

## Authentication

Browser callers authenticate with the signed httpOnly `overlay_session` cookie. Native and service callers may use bearer tokens on routes that support them.

## Request shapes

The generated reference includes:

* Query parameters.
* JSON request bodies.
* Multipart form-data request bodies.
* Path parameters for dynamic content routes.

Stable response schemas are documented in workflow pages when available. Some routes return provider-specific or streaming data and intentionally use route-specific response shapes.

## Error shape

Most JSON errors include at least:

```json theme={null}
{
  "error": "Human-readable message",
  "code": "machine_readable_code"
}
```

Routes may include additional fields.

## API keys and extensions

`/api/v1/api-keys` exists in the route tree but currently returns `501` because API key management is not exposed yet.

`/api/v1/extensions/[extensionId]/[...path]` is an extension proxy route and is intentionally excluded from the stable public API reference.

## Administration

The `/api/v1/admin/*` routes are role-protected endpoints for audit, principal management, and usage/budget control. See the [Admin workflow](./workflows/admin) for request shapes and role requirements.