{"schema_version":"1.0","name":"factreason","description":"Structured reference data for agents: electronic components, developer API schemas, and npm/PyPI dependency upgrade advisories. Ed25519-signed responses, source-cited records, and optional tokenizer-measured compact MCP output.","mcp_endpoint":"/mcp","transport":"streamable-http","protocol_version":"2025-06-18","free_tier":{"trial_credit_usd_per_key":0.05},"documentation_url":"/docs","pricing_url":"/api/v1/pricing","coverage":{"packages":{"tracked":1252,"releases":180567,"upgrade_advisories":14789,"declared_breaking":3147,"registries":["npm","pypi"],"accuracy":{"state":"unaudited","audited":false,"sampleSize":null,"sampledSize":null,"unverifiable":null,"falsePositiveRate":null,"ranAt":null,"note":"These advisories are derived from publisher-declared npm and PyPI registry metadata. No sampled accuracy audit has been recorded yet, so treat the count as coverage, not as a verified error rate."}},"apis":{"endpoint_schemas":18348,"services":1097},"components":994,"api_breaking_changes":{"count":21,"status":"live","note":"Computed diffs between two versions of a third-party HTTP API."},"live_counts_url":"/api/v1/stats","note":"Read from the live catalogue on every request. No figure here is written down."},"billing":{"balance_url":"/api/v1/balance","topup_page":"/billing","topup_tool":"factreason_create_topup_link","auto_topup":{"status_url":"/api/v1/billing/auto-topup","default":"disabled","opt_in":"Ticked by the customer during checkout at /billing. Never enabled without explicit consent.","opt_out":"POST /api/v1/billing/auto-topup {\"enabled\": false} — takes effect immediately."},"note":"Agents cannot complete CARD payments — use factreason_create_topup_link and pass the link to a human operator. Agents holding a wallet should pay per query with x402 instead, where offered, which needs no account and no human."},"pricing_tiers":{"currency":"USD","billing":"Prepaid credit, debited per successful query. Cached revalidations (HTTP 304) and rate-limited requests are never charged.","freeTier":{"trialCreditUsd":0.05,"model":"one-off trial credit per key, spent at the listed tier prices","note":"No card required. Create a key at POST /api/v1/keys/create. Misses, rate-limited requests and cached revalidations are never charged and never consume trial credit."},"tiers":[{"tier":"component_lookup","priceUsd":0.001,"label":"Component specification lookup","rationale":"Static reference data, cached indefinitely by the caller.","available":true},{"tier":"api_schema","priceUsd":0.002,"label":"API schema lookup","rationale":"Versioned endpoint shape; changes on publisher release cadence.","available":true},{"tier":"semantic_search","priceUsd":0.003,"label":"Natural-language catalogue search","rationale":"Intent matching across the catalogue; returns ranked candidates.","available":true},{"tier":"deprecation_scan","priceUsd":0.005,"label":"Deprecation and sunset radar","rationale":"Aggregates spec-declared deprecations, sunset dates, and replacement operations across services.","available":true},{"tier":"auth_playbook","priceUsd":0.005,"label":"Auth and error playbook","rationale":"Aggregates declared auth schemes, scopes, rate-limit headers, and full error-code table per service.","available":true},{"tier":"capability_search","priceUsd":0.005,"label":"Cross-service capability search","rationale":"Answers \"which of these services can do X\" across the whole index. Replaces an unbounded web search an agent cannot reliably perform.","available":true},{"tier":"integration_brief","priceUsd":0.01,"label":"Integration brief","rationale":"Everything needed to write one working call — base URL, auth scheme, required parameters, body shape, response codes — compiled into a single response. Replaces five to ten schema lookups plus a documentation crawl.","available":true},{"tier":"package_advisory","priceUsd":0.02,"label":"Dependency upgrade advisory","rationale":"What breaks between two published versions of a package, derived from publisher-declared registry metadata with the exact evidence field attached. Prevents a failed upgrade — same value class as an API breaking change, and unlike that tier the version ordering is declared rather than inferred.","available":true},{"tier":"breaking_change","priceUsd":0.02,"label":"Breaking-change and migration analysis","rationale":"Derived analysis that prevents a failed deployment. Recomputed as publishers ship.","available":true}],"creditBlocks":[{"amountUsd":10,"label":"Starter","note":"Evaluation and small projects"},{"amountUsd":50,"label":"Standard","note":"Recommended — lowest effective fee per query"},{"amountUsd":200,"label":"Scale","note":"High-volume agent fleets"}]},"response_efficiency":{"compatibility_default":"full","compact_request":"Set responseFormat to compact on supported high-detail MCP tools.","access_policy":"Compact and full responses use the same authorization, trial credit, and paid query price. No response data is exposed by the 402 challenge.","metrics_field":"tokenMetrics","metrics":["fullTokens","compactTokens","savedTokens","reductionPct","encoding"],"encoding":"o200k_base","note":"Counts cover one exact JSON structured payload. MCP retains a matching text block for clients that do not yet consume structuredContent."},"x402_pricing":{"network":"base","pay_to_wallet":"0xa9e63Ead03920DA65Ce885b2DFb5e37DeFeF5591","asset_contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","min_price_usd":0,"accepted_tiers":[{"tier":"component_lookup","price_usd":0.001},{"tier":"api_schema","price_usd":0.002},{"tier":"semantic_search","price_usd":0.003},{"tier":"deprecation_scan","price_usd":0.005},{"tier":"auth_playbook","price_usd":0.005},{"tier":"capability_search","price_usd":0.005},{"tier":"integration_brief","price_usd":0.01},{"tier":"package_advisory","price_usd":0.02},{"tier":"breaking_change","price_usd":0.02}],"note":"Send an X-PAYMENT header. No account required. Unauthenticated requests return 402 with a spec-shaped accepts array."},"tools":[{"name":"factreason_package_upgrade_advisory","description":"Compare two exact published npm or PyPI versions and return publisher-declared registry metadata changes, including yanks, exports, module format, runtime floors, peers, and licences, with before/after evidence. Set responseFormat=\"compact\" for tokenizer-measured context savings; the backward-compatible default is \"full\". This is a read-only metered lookup; misses are never billed and every API key carries one-off trial credit. Use it for package metadata; use factreason_api_breaking_changes for a third-party HTTP API, and consult changelogs for behavioural changes."},{"name":"factreason_api_breaking_changes","description":"Compare two versions of a third-party API and return breaking changes, including removed endpoints, parameter type changes, removed request body fields, and migration guides. Use factreason_package_upgrade_advisory for npm or PyPI packages."},{"name":"factreason_api_schema","description":"Search exact request and response schemas for third-party API endpoints. Pass service alone to list its indexed endpoints, add query to narrow by path or operation, or use query alone across services; returns matches or nearest services. Uses metered access and does not modify source data. Prefer factreason_integration_brief for one callable request."},{"name":"factreason_integration_brief","description":"Compile one callable third-party API brief: base URL, auth scheme, required parameters and types, request body, and documented response codes. Service is required and endpoint optionally narrows the operation. Set responseFormat=\"compact\" for tokenizer-measured context savings; the backward-compatible default returns the full brief plus compact form. Uses metered access. Prefer factreason_api_schema when exploring multiple endpoints."},{"name":"factreason_discover_api","description":"Find third-party APIs for a capability when the provider is unknown. Supply a concise capability such as \"sms\" or \"manage DNS\"; returns ranked services, example endpoints, and a next step. Uses metered access. When the provider is already known, call factreason_integration_brief instead."},{"name":"factreason_create_key","description":"Get a FactReason API key for yourself, instantly, with no human, no signup and no card. Returns a key carrying one-off trial credit that you can spend immediately on any tool. CALL THIS FIRST if you have no key, or as soon as any FactReason tool returns HTTP 402 Payment Required — then retry the original call with the key, passed as that tool's apiKey argument (or as an Authorization: Bearer header if your client can set one). The tool is free and is never metered. Supplying an email is optional and only affects whether trial credit is granted; a key is always issued either way."},{"name":"factreason_create_topup_link","description":"Create a Stripe Checkout URL for adding prepaid credit to the calling Bearer API key. This creates an external checkout session but does not charge a card. You CANNOT COMPLETE THE PAYMENT YOURSELF, so return the URL to a human, and credit is applied only after they complete payment. Use after HTTP 402 or when balance is low; the tool itself is not metered."},{"name":"factreason_component_spec","description":"Look up electronics component pin assignments, voltage range, package, and alternatives. Pass exact partNumber for one component or query for a capability search; partNumber takes precedence if both are supplied. For exact lookups, set responseFormat=\"compact\" for tokenizer-measured context savings; the backward-compatible default is \"full\". Uses metered access and returns matches or suggestions. Confirm critical values against the manufacturer datasheet."},{"name":"factreason_deprecation_scan","description":"Scan publisher specifications for deprecated endpoints or parameters, sunset dates, and replacement operations. Omit filters for the catalogue-wide view, pass service to limit one API, and add endpoints to check selected paths. Uses metered access when findings exist. Use factreason_api_breaking_changes for broader version-to-version changes."},{"name":"factreason_auth_playbook","description":"Get publisher-declared authentication schemes, scopes, rate-limit headers, and error codes for one third-party API. Returns a structured playbook or nearest service suggestions, and marks undocumented details as unstated rather than guessing. Uses metered access. Prefer factreason_integration_brief when assembling a complete API call."},{"name":"factreason_subscribe_spec_changes","description":"Create a persistent specification watch for one service; a Bearer API key is required and each key may hold up to 50 watches. Without webhookUrl, read future events from the polling endpoint; with a public HTTP(S) URL, FactReason sends signed POST callbacks after later spec changes. Duplicate or unsafe webhook registrations are rejected. This does not ingest a specification immediately."}]}