{"openapi":"3.1.0","info":{"title":"FactReason Agent API","version":"2.1.0","description":"Public access, discovery, correction, and paid reference-data routes. Catalogue results remain protected by Bearer-key or x402 authorization."},"servers":[{"url":"https://factreason.com"}],"security":[{"bearerAuth":[]}],"paths":{"/health":{"get":{"summary":"Check service and database health","security":[],"responses":{"200":{"description":"Healthy"},"503":{"description":"Unavailable"}}}},"/api/v1/stats":{"get":{"summary":"Get live catalogue counts","security":[],"responses":{"200":{"description":"Public aggregate counts"}}}},"/api/v1/pricing":{"get":{"summary":"Get the live query rate card","security":[],"responses":{"200":{"description":"Pricing and trial credit"}}}},"/api/v1/keys/create":{"post":{"summary":"Create a self-service API key","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":200}}}}}},"responses":{"200":{"description":"Key created"},"429":{"description":"Creation limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/v1/packages/{registry}/{name}/advisory":{"get":{"summary":"Compare two exact npm or PyPI package versions","parameters":[{"name":"registry","in":"path","required":true,"schema":{"type":"string","enum":["npm","pypi"]}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":true,"schema":{"type":"string"}},{"name":"to","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Authorized advisory or an unbilled miss"},"402":{"description":"Payment required; contains requirements only, never advisory data"}}}},"/api/v1/report-error":{"post":{"summary":"Submit a correction for private operator review","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recordId"],"properties":{"recordId":{"type":"string","maxLength":200},"field":{"type":"string","maxLength":120},"observedValue":{"type":"string","maxLength":2000},"expectedValue":{"type":"string","maxLength":2000},"sourceUrl":{"type":"string","format":"uri","maxLength":1000},"reporter":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Queued; returns a report ID only"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Five-report hourly IP limit reached"}}}},"/api/v1/packages/stats":{"get":{"summary":"Get package catalogue counts","security":[],"responses":{"200":{"description":"Indexed packages, releases, advisories and breaking counts"}}}},"/api/v1/balance":{"get":{"summary":"Check remaining prepaid and trial credit","description":"Free. Requires a Bearer key; never billed.","responses":{"200":{"description":"Balance and remaining trial credit"},"401":{"description":"No Bearer key supplied","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Unknown key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/v1/components":{"get":{"summary":"Search electronic components","description":"Paid: $0.001 per successful query (tier `component_lookup`). Misses, HTTP 304 revalidations and rate-limited requests are never billed.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text part or capability search"},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["full","compact"]},"description":"Use `compact` for a token-reduced body. Same authorization and price as `full`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Authorized result, or an unbilled miss with `found: false` and nearest matches"},"304":{"description":"Cached revalidation. Never billed."},"402":{"description":"Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss."},"429":{"description":"Rate limited. Never billed; honour `Retry-After`."}}}},"/api/v1/components/{partNumber}":{"get":{"summary":"Look up one component by exact part number","description":"Paid: $0.001 per successful query (tier `component_lookup`). Misses, HTTP 304 revalidations and rate-limited requests are never billed.","parameters":[{"name":"partNumber","in":"path","required":true,"schema":{"type":"string"},"description":"Exact manufacturer part number, e.g. `STM32F401RE`"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["full","compact"]},"description":"Use `compact` for a token-reduced body. Same authorization and price as `full`."},{"name":"asOf","in":"query","required":false,"schema":{"type":"string"},"description":"Return the record as it stood at this timestamp"}],"responses":{"200":{"description":"Authorized result, or an unbilled miss with `found: false` and nearest matches"},"304":{"description":"Cached revalidation. Never billed."},"402":{"description":"Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss."},"429":{"description":"Rate limited. Never billed; honour `Retry-After`."}}}},"/api/v1/search/semantic":{"get":{"summary":"Search the catalogue by natural-language intent","description":"Paid: $0.003 per successful query (tier `semantic_search`). Misses, HTTP 304 revalidations and rate-limited requests are never billed.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Intent, e.g. `3.3V ARM MCU with SPI`"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Authorized result, or an unbilled miss with `found: false` and nearest matches"},"304":{"description":"Cached revalidation. Never billed."},"402":{"description":"Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss."},"429":{"description":"Rate limited. Never billed; honour `Retry-After`."}}}},"/api/v1/apis":{"get":{"summary":"Search third-party API endpoint schemas","description":"Paid: $0.002 per successful query (tier `api_schema`). Misses, HTTP 304 revalidations and rate-limited requests are never billed.","parameters":[{"name":"service","in":"query","required":false,"schema":{"type":"string"},"description":"Service filter, e.g. `Stripe`"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Endpoint path or operation fragment"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["full","compact"]},"description":"Use `compact` for a token-reduced body. Same authorization and price as `full`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Authorized result, or an unbilled miss with `found: false` and nearest matches"},"304":{"description":"Cached revalidation. Never billed."},"402":{"description":"Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss."},"429":{"description":"Rate limited. Never billed; honour `Retry-After`."}}}},"/api/v1/apis/{service}/brief":{"get":{"summary":"Compile one callable integration brief","description":"Paid: $0.010 per successful query (tier `integration_brief`). Misses, HTTP 304 revalidations and rate-limited requests are never billed.","parameters":[{"name":"service","in":"path","required":true,"schema":{"type":"string"}},{"name":"endpoint","in":"query","required":false,"schema":{"type":"string"},"description":"Path or operation fragment selecting one call"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["full","compact"]},"description":"Use `compact` for a token-reduced body. Same authorization and price as `full`."}],"responses":{"200":{"description":"Authorized result, or an unbilled miss with `found: false` and nearest matches"},"304":{"description":"Cached revalidation. Never billed."},"402":{"description":"Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss."},"429":{"description":"Rate limited. Never billed; honour `Retry-After`."}}}},"/api/v1/apis/{service}/deprecations":{"get":{"summary":"List declared deprecations and sunset dates for one service","description":"Paid: $0.005 per successful query (tier `deprecation_scan`). Misses, HTTP 304 revalidations and rate-limited requests are never billed.","parameters":[{"name":"service","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Authorized result, or an unbilled miss with `found: false` and nearest matches"},"304":{"description":"Cached revalidation. Never billed."},"402":{"description":"Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss."},"429":{"description":"Rate limited. Never billed; honour `Retry-After`."}}}},"/api/v1/apis/deprecation-scan":{"get":{"summary":"Scan the catalogue for declared deprecations","description":"Paid: $0.005 per successful query (tier `deprecation_scan`). Misses, HTTP 304 revalidations and rate-limited requests are never billed.","parameters":[{"name":"service","in":"query","required":false,"schema":{"type":"string"},"description":"Optional service filter"}],"responses":{"200":{"description":"Authorized result, or an unbilled miss with `found: false` and nearest matches"},"304":{"description":"Cached revalidation. Never billed."},"402":{"description":"Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss."},"429":{"description":"Rate limited. Never billed; honour `Retry-After`."}}}},"/api/v1/apis/auth-playbook":{"get":{"summary":"Get auth schemes, scopes, rate-limit headers and error codes","description":"Paid: $0.005 per successful query (tier `auth_playbook`). Misses, HTTP 304 revalidations and rate-limited requests are never billed. Undocumented details are returned as `unstated`, never as a plausible default.","parameters":[{"name":"service","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Authorized result, or an unbilled miss with `found: false` and nearest matches"},"304":{"description":"Cached revalidation. Never billed."},"402":{"description":"Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss."},"429":{"description":"Rate limited. Never billed; honour `Retry-After`."}}}},"/api/v1/discover":{"get":{"summary":"Find which indexed service can perform a capability","description":"Paid: $0.005 per successful query (tier `capability_search`). Misses, HTTP 304 revalidations and rate-limited requests are never billed.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Capability, e.g. `send an SMS`"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Authorized result, or an unbilled miss with `found: false` and nearest matches"},"304":{"description":"Cached revalidation. Never billed."},"402":{"description":"Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss."},"429":{"description":"Rate limited. Never billed; honour `Retry-After`."}}}},"/api/v1/apis/{service}/breaking-changes":{"get":{"summary":"Compare two versions of a third-party API","description":"OFFLINE: this tier is withdrawn and returns HTTP 503 without billing. Breaking-change analysis is offline pending revalidation. A quality audit found that the previously published diffs were computed from mis-ordered specification versions and are not trustworthy, so they have been withdrawn rather than served. This endpoint is not billed while in this state. Schema lookups (GET /api/v1/apis) are unaffected.","parameters":[{"name":"service","in":"path","required":true,"schema":{"type":"string"}},{"name":"fromVersion","in":"query","required":false,"schema":{"type":"string"}},{"name":"toVersion","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"503":{"description":"Withdrawn pending revalidation. Returns `billed: false` and alternatives. Do not read this as \"no breaking changes exist\"."}}}},"/api/v1/apis/watches/subscribe":{"post":{"summary":"Watch a service specification for changes","description":"Requires a Bearer key. Registers a polling or signed-webhook watch; does not ingest a specification immediately.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["serviceName"],"properties":{"serviceName":{"type":"string","maxLength":200},"webhookUrl":{"type":"string","format":"uri","description":"Optional public HTTP(S) URL for signed change callbacks; omit to poll"}}}}}},"responses":{"200":{"description":"Watch registered"},"400":{"description":"Missing serviceName, or a duplicate or unsafe webhook URL","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"description":"No Bearer key supplied","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/mcp":{"post":{"summary":"Use the Streamable HTTP MCP endpoint","description":"Initialize the server and call tools/list for authoritative tool schemas. GET and DELETE answer 405 by design: this server offers no SSE stream.","responses":{"200":{"description":"JSON-RPC response"},"402":{"description":"x402 payment challenge for protected tool data"},"405":{"description":"Method not allowed. Required by the Streamable HTTP spec when no SSE stream is offered."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"FactReason API key"}}},"externalDocs":{"description":"FactReason documentation","url":"https://factreason.com/docs"}}