{"openapi":"3.1.0","info":{"title":"Fetchgate API","version":"0.1.0","summary":"Web-content API for AI agents (placeholder name).","description":"Fetch clean Markdown or structured metadata from any URL, server-side, with scripts/nav/ad boilerplate stripped out."},"servers":[{"url":"https://fetchgate.dev","description":"Current host"}],"paths":{"/v1/read":{"get":{"operationId":"readUrl","summary":"Fetch a URL and convert its main content to Markdown.","parameters":[{"name":"url","in":"query","required":true,"description":"The absolute http(s) URL to fetch.","schema":{"type":"string","format":"uri"}},{"name":"format","in":"query","required":false,"description":"Set to `text` to receive raw Markdown instead of JSON.","schema":{"type":"string","enum":["json","text"],"default":"json"}}],"responses":{"200":{"description":"Successful extraction.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"markdown":{"type":"string"},"fetchedAt":{"type":"string","format":"date-time"}},"required":["url","markdown","fetchedAt"]}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Invalid or disallowed URL.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Free tier exhausted; payment required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Upstream fetch failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}}}}},"/v1/meta":{"get":{"operationId":"getMeta","summary":"Fetch a URL and return structured page metadata.","parameters":[{"name":"url","in":"query","required":true,"description":"The absolute http(s) URL to fetch.","schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Successful extraction.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"canonical":{"type":"string","format":"uri"},"language":{"type":"string"},"faviconUrl":{"type":"string","format":"uri"},"publishedTime":{"type":"string"},"modifiedTime":{"type":"string"},"openGraph":{"type":"object","additionalProperties":{"type":"string"}},"twitter":{"type":"object","additionalProperties":{"type":"string"}},"fetchedAt":{"type":"string","format":"date-time"}},"required":["url","fetchedAt","openGraph","twitter"]}}}},"400":{"description":"Invalid or disallowed URL.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Free tier exhausted; payment required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Upstream fetch failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}}}}},"/v1/products":{"get":{"operationId":"listProducts","summary":"Public catalog of digital-goods products for sale (no payment required).","responses":{"200":{"description":"The current product catalog.","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"priceUsd":{"type":"number"},"currency":{"type":"string","enum":["USD"]},"format":{"type":"string"},"file":{"type":"string"},"sizeBytes":{"type":"integer"},"sha256":{"type":"string"},"humanUrl":{"type":"string","format":"uri"}},"required":["id","name","description","priceUsd","currency","format","sizeBytes","sha256","humanUrl"]}}},"required":["products"]}}}}}}},"/v1/buy/{id}":{"get":{"operationId":"buyProduct","summary":"Buy a product via x402. 402 without payment; returns a signed download URL on success.","parameters":[{"name":"id","in":"path","required":true,"description":"Product id from GET /v1/products.","schema":{"type":"string"}}],"responses":{"200":{"description":"Payment accepted; a signed, time-limited download URL.","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"downloadUrl":{"type":"string","format":"uri"},"expiresInSeconds":{"type":"integer"}},"required":["productId","downloadUrl","expiresInSeconds"]}}}},"402":{"description":"Payment required — either an x402 challenge (accepts[]) once a wallet is configured, or an explanatory JSON 402 while x402 is not yet enabled.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown product id.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}}}}},"/v1/download/{id}":{"get":{"operationId":"downloadProduct","summary":"Download a purchased product via a signed, time-limited URL from /v1/buy/:id.","parameters":[{"name":"id","in":"path","required":true,"description":"Product id.","schema":{"type":"string"}},{"name":"exp","in":"query","required":true,"description":"Unix-seconds expiry embedded in the signed URL.","schema":{"type":"integer"}},{"name":"sig","in":"query","required":true,"description":"HMAC-SHA256 signature over `${id}.${exp}`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The product file."},"403":{"description":"Missing, invalid, or expired signature — call /v1/buy/:id again.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Unknown product id.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Server misconfiguration or the file is missing in storage.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}}}}},"/mcp":{"post":{"operationId":"mcpJsonRpc","summary":"Model Context Protocol (MCP) server — Streamable HTTP transport (JSON-RPC 2.0).","description":"A single JSON-RPC 2.0 endpoint implementing MCP's Streamable HTTP transport: `initialize`, `tools/list`, and `tools/call`. Exposes four tools — `read_url` and `get_metadata` (wrapping /v1/read and /v1/meta, same free-tier limit and x402 pricing), `list_products` (wrapping /v1/products), and `get_purchase_info` (explains the /v1/buy/:id x402 purchase flow for a product). Send `MCP-Protocol-Version: 2025-06-18` on requests after `initialize`. Responses are always a single `application/json` object (no SSE stream). See /llms.txt for a plain-language summary.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","number","null"]},"method":{"type":"string","enum":["initialize","ping","tools/list","tools/call"]},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"JSON-RPC success or error result for a request carrying an `id`.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Accepted — the body was a JSON-RPC notification or response (no `id`), so there is no reply."},"400":{"description":"Malformed JSON, a non-JSON-RPC body, or an unsupported MCP-Protocol-Version.","content":{"application/json":{"schema":{"type":"object"}}}}}},"get":{"operationId":"mcpSseNotOffered","summary":"Always 405 — this server has no server-initiated SSE stream to open.","responses":{"405":{"description":"Method Not Allowed. Use POST for JSON-RPC requests."}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","summary":"Agent-facing plain-text description of this API.","responses":{"200":{"description":"llms.txt content.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","summary":"This OpenAPI document.","responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Optional API key for authenticated/paid access. TODO: pay-per-request via x402 is planned as an alternative to a pre-provisioned key."}}}}