Docs

HTTP API — Gatefee API 0.1.0

Generated from the OpenAPI document the SDKs are built from.

MethodPathWhat it doesNeeds a key
GET/.well-known/oauth-protected-resource/mcpRFC 9728 metadata for the MCP endpoint (path-inserted form). Present only when OAuth is configured (ADR-0039).No
GET/.well-known/oauth-protected-resourceThe same document at the root well-known URI (the MCP client fallback).No
GET/.well-known/oauth-authorization-serverRFC 8414 authorization-server metadata. Present only when OAuth is configured (ADR-0039).No
GET/oauth/authorizeThe 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/tokenThe 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/healthzLiveness + database reachability.No
GET/.well-known/jwks.jsonPublic receipt-signing keys (empty until Phase 4).No
GET/v1/auth/checkIdentify the presented API key. Any scope.Yes
GET/.well-known/http-message-signatures-directoryPublic keys that sign Gatefee's outbound requests (Web Bot Auth). Publishers verify or block us by these.No
GET/v1/publisher/sourcesThe publisher's ingestion sources. Scope `publisher:manage`.Yes
POST/v1/publisher/sourcesAdd an ingestion source (https only).Yes
PATCH/v1/publisher/sources/{id}Change poll interval, pause/resume, or hygiene overrides. Audited.Yes
GET/v1/publisher/rightsThe publisher's rights grants. Scope `publisher:manage`.Yes
POST/v1/publisher/rightsAdd 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/onboardingThe 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/pricingPublic, machine-readable pricing. No authentication; rate-limited per client.No
GET/v1/sampleThe 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/publishersPublishers 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}/statusWhether 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/verifyServer-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/searchFull-text search over licensed, current documents. Metered as one flat-priced search; no receipt.Yes
GET/v1/usageThe caller's own usage and spend. Default window - the current billing period (calendar month, UTC). At most 366 days.Yes
POST/v1/webhooks/stripeThe payment provider's webhook endpoint (Phase 7, ADR-0041). Not for API callers.No