# OpenAPI schema

> The complete, machine-readable VerifiedInbox API contract (OpenAPI 3.1), for code generators, API clients and AI agents.

The whole VerifiedInbox REST API is described in one **OpenAPI 3.1** document. It is the only API contract: everything else follows it.

- **[`https://getverifiedinbox.com/openapi.json`](https://getverifiedinbox.com/openapi.json)**
- The API serves the same document at `https://api.getverifiedinbox.com/openapi.json`.

Use it to generate a client (openapi-generator, openapi-typescript, oapi-codegen, …), import the API into Postman or Insomnia, or give it to an AI agent so it knows every operation and payload. Its description also contains the API guide: authentication, conventions, core concepts and test mode.

## Everything follows the schema

The document is built from the same code that routes requests, so an endpoint can't exist without being in it. Everything else is generated from the document:

- the endpoint tables in the [API reference](https://getverifiedinbox.com/docs/api.md) and [get-started.md](https://getverifiedinbox.com/get-started.md),
- the [MCP tools](https://getverifiedinbox.com/docs/mcp.md): each tool's arguments (types, allowed values, which are required, descriptions) are taken from the API operations it wraps,
- the TypeScript types our own web app uses.

The build fails if any of these is out of date, and our end-to-end tests check real API responses against the schema. If the document says a field exists, the API returns it.

## VerifiedInbox extensions

Each operation carries a few extra fields beyond standard OpenAPI:

| Field | Meaning |
|---|---|
| `x-access` | Who may call it: `public`, `guest` (works anonymously with a guest token), `account` (signed in or API key), `paid`, `admin` or `webhook`. |
| `x-required-scope` | The API key scope needed, e.g. `applications:write`. |
| `x-idempotency` | `required`, `optional` or `none`: send an `Idempotency-Key` header so retries never charge or order twice. |
| `x-mcp-tools` | The MCP tool(s) that do the same thing, so agents can switch between REST and MCP freely. |
| `x-mcp-note` | Why an operation has no MCP tool (for example, file downloads). |

Errors use one shape everywhere (`Error` in the schema): a stable `code`, a plain-English `message` and, when there is something to do, a `next_action` such as signing in or paying.

## Authentication

The document declares the schemes the API accepts: bearer tokens (API keys `vi_live_…` / `vi_test_…`, or an OAuth access token from an MCP client), the guest token header (`VI-Guest-Token`) for anonymous drafts, and the browser cookies the web app uses. Each operation's `security` lists which ones work for it. See [API reference → Authentication](https://getverifiedinbox.com/docs/api.md#authentication).

## Versioning

Paths start with `/v1`. Within v1 we only add things (new operations, new optional fields, new enum values), so generated clients should tolerate unknown enum values. Breaking changes would ship as `/v2`.