Developers & AI
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- 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 and get-started.md,
- the MCP tools: 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.
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.