API conventions

The HTTP API on https://webmcp-gateway-preview.etadros.workers.dev is small. The daemon uses it to pair a device, agents use the management MCP endpoint, and OAuth clients register themselves. The machine-readable description is https://webmcp-gateway-preview.etadros.workers.dev/openapi.json (OpenAPI 3.1); this page states the rules that hold across all of it.

Start without an account or a key

Nothing here needs a pre-issued API key, and the first call needs no account.

POST https://webmcp-gateway-preview.etadros.workers.dev/api/v1/device/start is anonymous. It returns verification_uri_complete, the one link a human opens to sign in (which creates the free account) and approve the device. Then poll POST https://webmcp-gateway-preview.etadros.workers.dev/api/v1/device/poll. This is what webmcp up does.
POST https://webmcp-gateway-preview.etadros.workers.dev/oauth/register registers an OAuth client immediately (RFC 7591), with no approval step. See auth.md.
POST https://webmcp-gateway-preview.etadros.workers.dev/mcp offers check_handle, start_setup, setup_status with no credential.

The free tier (1 handle, 1 device, 1 server, 1 connector) is what you get. See pricing.

Versioning

The version is in the path: /api/v1. Every response under /api/ carries an API-Version: 1 header. Within a version, changes are additive only: new operations, new optional request fields, new response fields, new error codes. Clients must ignore fields they do not know. Anything that would break a correct client ships under a new path (/api/v2) while /api/v1 keeps working.

The discovery documents under /.well-known/, the management MCP endpoint and the OAuth endpoints follow their own specifications and are versioned by those.

Deprecation and sunset policy

An operation or version that will be retired is announced at least 6 months before it stops working.
From the announcement on, its responses carry a Deprecation header (RFC 9745) with the date it was deprecated and a Sunset header (RFC 8594) with the date it will be removed, plus a Link header with rel="deprecation" pointing at this page.
The announcement is recorded in the changelog below and in the x-deprecation-policy block of the OpenAPI document, and account holders are told by email.
After the sunset date the operation answers 410 with the usual JSON error body.

Nothing is deprecated today.

Rate limits

Limits are per client IP, in fixed windows. Rate-limited operations report where you stand on every response, not only on refusal:

Header	Meaning
`RateLimit-Policy`	The quota, for example `"device-start";q=10;w=900` (10 requests per 900 seconds)
`RateLimit`	What is left, for example `"device-start";r=9;t=412` (9 remaining, resets in 412 seconds)
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`	The same three numbers for clients that read the older names. Reset is in seconds
`Retry-After`	On `429` only: seconds to wait

Operation	Limit
`POST /api/v1/device/start`	10 per 15 minutes
`POST /api/v1/pair`	20 per 15 minutes
Requests to `/api/` paths that match no operation	60 per minute

On 429, wait Retry-After seconds and try again. Do not retry faster. Relayed MCP calls on a user's own endpoint are not metered for cost, only limited against abuse.

Errors

Every error under /api/ is JSON, whatever the status: unknown paths (404), wrong methods (405 with an Allow header), bad bodies (400), rate limits (429) and server faults (5xx).

{
  "error": "code_not_found",
  "message": "That pairing code is unknown, expired or already used.",
  "hint": "Create a new code on the dashboard, or run `webmcp up`, which needs no code.",
  "docs": "https://webmcp-gateway-preview.etadros.workers.dev/docs/api"
}

error is a stable machine code: match on it, never on message. hint says what to do next. The codes:

not_found: No API operation exists at this path.
method_not_allowed: This operation does not support that HTTP method.
invalid_request: The request body is malformed or a field is missing or invalid.
unsupported_media_type: The request body must be JSON.
rate_limited: Too many requests from this address in the current window.
code_not_found: That pairing code is unknown, expired or already used.
device_name_taken: Another device on this handle already has that name.
device_limit: The plan allows no more devices on this handle.
hardware_already_paired: This machine is already paired to another free handle.
authorization_pending: The human has not approved the device yet.
slow_down: Polling faster than the allowed interval.
access_denied: The human declined to approve this device.
expired_token: This device authorization has expired or was already used.
internal_error: The gateway failed to handle the request.

The management MCP endpoint answers with JSON-RPC 2.0 error objects instead, as MCP requires, and the OAuth endpoints with RFC 6749 error objects.

Changelog

2026-09-21: /api/v1 documented. Added RateLimit headers, hint and docs on every error, 405 with Allow, and the API-Version header. No breaking changes.

OpenAPI, API catalog, auth.md, agent-driven setup, security model.