MCP quickstartOne URL, one key: connect Claude Code, Claude Desktop or any MCP client.
The receipt formatEvery field, how to verify one offline, and a worked example you can reproduce.
HTTP API — Gatefee API 0.1.0
Generated from the OpenAPI document the SDKs are built from.
| Method | Path | What it does | Needs a key |
|---|---|---|---|
| GET | /.well-known/oauth-protected-resource/mcp | RFC 9728 metadata for the MCP endpoint (path-inserted form). Present only when OAuth is configured (ADR-0039). | No |
| GET | /.well-known/oauth-protected-resource | The same document at the root well-known URI (the MCP client fallback). | No |
| GET | /.well-known/oauth-authorization-server | RFC 8414 authorization-server metadata. Present only when OAuth is configured (ADR-0039). | No |
| GET | /oauth/authorize | The authorization endpoint: response_type=code, PKCE S256 (required), resource = the canonical /mcp URI (required). A valid request is parked and the browser is sent to the console consent page; an invalid one is answered here and never redirected. | No |
| POST | /oauth/token | The token endpoint: grant_type authorization_code (code, redirect_uri, client_id, code_verifier, resource) or refresh_token (refresh_token, client_id, optional resource and scope). Public clients only; any client authentication is refused. | No |
| GET | /healthz | Liveness + database reachability. | No |
| GET | /.well-known/jwks.json | Public receipt-signing keys (empty until Phase 4). | No |
| GET | /v1/auth/check | Identify the presented API key. Any scope. | Yes |
| GET | /.well-known/http-message-signatures-directory | Public keys that sign Gatefee's outbound requests (Web Bot Auth). Publishers verify or block us by these. | No |
| GET | /v1/publisher/sources | The publisher's ingestion sources. Scope `publisher:manage`. | Yes |
| POST | /v1/publisher/sources | Add an ingestion source (https only). | Yes |
| PATCH | /v1/publisher/sources/{id} | Change poll interval, pause/resume, or hygiene overrides. Audited. | Yes |
| GET | /v1/publisher/rights | The publisher's rights grants. Scope `publisher:manage`. | Yes |
| POST | /v1/publisher/rights | Add a grant. `price_micro` defaults to the platform list price and must sit inside the band of GET /v1/pricing. 409 if a grant for the same scope and purpose is already effective in the window, or — `reason` `domain_unverified` — if an allow is asked for while a verified domain of the publisher fails verification (a deny is always accepted). | Yes |
| PATCH | /v1/publisher/rights/{id} | End a grant. Grants are immutable; `effective_to` is the only field that can change, and only to shorten the grant. | Yes |
| GET | /v1/publisher/onboarding | The post-connect checklist. Scope `publisher:manage`. Six items in order — feed reachable, parsed, first articles ingested, rights block recorded, sample document rendered, agreement signed — each computed now from the publisher's own rows. A red item carries a machine-readable `hint` code (the console turns it into words) and `support_url`; a green one carries neither. Changes nothing. | Yes |
| GET | /v1/pricing | Public, machine-readable pricing. No authentication; rate-limited per client. | No |
| GET | /v1/sample | The fixed sample set, so an agent can inspect the format before it licenses anything. No authentication; rate-limited per client. At most 5 current documents from the platform-operated sample publisher. Free and unmetered — no license, no usage event, no receipt — and the only content Gatefee ever serves without one. These documents cannot be retrieved through /v1/documents. | No |
| GET | /v1/publishers | Publishers that have signed the publisher agreement and are listed (listing is a default term with a per-publisher opt-out). A publisher is left out while serving from one of its verified domains is paused (a verification that lapsed 14 days ago or more). Names, document counts and section names only. No authentication; rate-limited per client. | No |
| GET | /v1/documents/{document_id} | Retrieve the current version of a document under a purpose. Metered and receipted. | Yes |
| GET | /v1/documents/{document_id}/versions/{version_id} | Retrieve a pinned version. | Yes |
| GET | /v1/documents/{document_id}/status | Whether a document or its current version has been revoked. Not billable. | Yes |
| GET | /v1/receipts/{receipt_id} | One of the caller's own receipts. | Yes |
| POST | /v1/receipts/verify | Server-side convenience. Offline verification against /.well-known/jwks.json is the real path. | Yes |
| GET | /v1/terms/{terms_hash} | The public terms document behind a receipt's terms_hash. No authentication. The body's sha256 equals terms_hash. | No |
| GET | /v1/terms/buyer/{version} | A public buyer-terms version, its text hash and status. No authentication. | No |
| POST | /v1/search | Full-text search over licensed, current documents. Metered as one flat-priced search; no receipt. | Yes |
| GET | /v1/usage | The caller's own usage and spend. Default window - the current billing period (calendar month, UTC). At most 366 days. | Yes |
| POST | /v1/webhooks/stripe | The payment provider's webhook endpoint (Phase 7, ADR-0041). Not for API callers. | No |