# FactReason — Structured Reference Data for AI Agents
> Token-efficient component and developer-API reference data. Every response is Ed25519-signed and source-cited.
> Accuracy is best-effort, not guaranteed — see /terms. Human and agent documentation: /docs.

## Documentation
- [Human quickstart and workflows](https://factreason.com/docs)
- [Full agent-readable documentation](https://factreason.com/llms-full.txt)
- [FactReason agent skill](https://factreason.com/skill.md)
- [OpenAPI description](https://factreason.com/openapi.json)
- [MCP discovery manifest](https://factreason.com/.well-known/mcp.json)

## Catalogue Size
- **Electronic components**: 994
- **API endpoint schemas**: 18348 across 1097 services
- **Package releases indexed**: 180567 across 1252 npm/PyPI packages, with 14789 upgrade advisories (3147 breaking)
- **Computed breaking changes**: 21
- Live counts: GET /api/v1/stats (free, no auth)

## Pricing
- **Component specification lookup**: $0.001 per query — Static reference data, cached indefinitely by the caller.
- **API schema lookup**: $0.002 per query — Versioned endpoint shape; changes on publisher release cadence.
- **Natural-language catalogue search**: $0.003 per query — Intent matching across the catalogue; returns ranked candidates.
- **Deprecation and sunset radar**: $0.005 per query — Aggregates spec-declared deprecations, sunset dates, and replacement operations across services.
- **Auth and error playbook**: $0.005 per query — Aggregates declared auth schemes, scopes, rate-limit headers, and full error-code table per service.
- **Cross-service capability search**: $0.005 per query — Answers "which of these services can do X" across the whole index. Replaces an unbounded web search an agent cannot reliably perform.
- **Integration brief**: $0.01 per query — 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.
- **Dependency upgrade advisory**: $0.02 per query — 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.
- **Breaking-change and migration analysis**: $0.02 per query — Derived analysis that prevents a failed deployment. Recomputed as publishers ship.
- **Trial credit**: eligible new users receive up to $0.05 once, subject to grant budgets and spent at per-tier prices. No card required. Create a key: POST /api/v1/keys/create
- Cached revalidations (HTTP 304) and rate-limited requests are never charged.
- Full pricing: GET /api/v1/pricing
- Documentation and repeatable workflows: GET /docs

## Paying
- **Agents with a wallet: pay per query with x402 — no account, no signup, no human.** Send an X-PAYMENT header; settlement is on-chain in USDC on base.
- x402 is accepted on: Component specification lookup ($0.001), API schema lookup ($0.002), Natural-language catalogue search ($0.003), Deprecation and sunset radar ($0.005), Auth and error playbook ($0.005), Cross-service capability search ($0.005), Integration brief ($0.01), Dependency upgrade advisory ($0.02), Breaking-change and migration analysis ($0.02).
- Unauthenticated requests return 402 with a spec-shaped `accepts` array. Any x402 client (e.g. x402-fetch) can pay it.
- **Agents without a wallet**: $0.05 of one-off trial credit on a self-service key from POST /api/v1/keys/create.
- Check your balance: GET /api/v1/balance (free, send Authorization: Bearer <key>)
- **Add credit by card**: open https://factreason.com/billing in a browser — a card needs a human.
- Agents without a wallet: call the `factreason_create_topup_link` MCP tool to generate a checkout link, then hand it to your operator.
- Credit is applied within seconds of Stripe confirming payment. Retry the original query then.
- **Automatic top-up** (optional, off by default): tick the box during checkout to keep a card on file and refill automatically when the balance runs low. You set the trigger, amount and a monthly limit. Turn it off any time at /billing or via POST /api/v1/billing/auto-topup {"enabled": false}. Status: GET /api/v1/billing/auto-topup
- **Token-Efficient Responses**: REST supports ?format=compact. Heavy MCP tools accept responseFormat="compact" and return tokenMetrics measured with o200k_base. The default remains "full" so existing integrations keep their response contract.

## Sample Components (994 total)
- **0402B151K500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402B222K500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402B471K500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402B682K500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG1R0C500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG1R5C500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG270J500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG2R2C500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG2R7C500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG300J500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG3R3C500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG4R7C500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG6R0C500NT (SMT业务专用)** (Generic): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402CG6R8C500NT** (FH Guangdong Fenghua Advanced Tech): Capacitors > Multilayer Ceramic Capacitors MLCC - SMD/SMT
- **0402WGF1005TCE** (UNI ROYAL Uniroyal Elec): Resistors > Chip Resistor - Surface Mount

## Sample API Endpoints (18348 total)
- ** API Client** (2018-02-01): GET /providers/Microsoft.Web/publishingUsers/web
- ** API Client** (2018-02-01): GET /providers/Microsoft.Web/sourcecontrols
- ** API Client** (2018-02-01): GET /providers/Microsoft.Web/sourcecontrols/{sourceControlType}
- ** API Client** (2018-02-01): GET /subscriptions/{subscriptionId}/providers/Microsoft.Web/billingMeters
- ** API Client** (2018-02-01): GET /subscriptions/{subscriptionId}/providers/Microsoft.Web/deploymentLocations
- ** API Client** (2018-02-01): GET /subscriptions/{subscriptionId}/providers/Microsoft.Web/geoRegions
- ** API Client** (2018-02-01): GET /subscriptions/{subscriptionId}/providers/Microsoft.Web/premieraddonoffers
- ** API Client** (2018-02-01): GET /subscriptions/{subscriptionId}/providers/Microsoft.Web/skus
- ** API Client** (2018-02-01): POST /subscriptions/{subscriptionId}/providers/Microsoft.Web/checknameavailability
- ** API Client** (2018-02-01): POST /subscriptions/{subscriptionId}/providers/Microsoft.Web/listSitesAssignedToHostName
- ** API Client** (2018-02-01): POST /subscriptions/{subscriptionId}/providers/Microsoft.Web/verifyHostingEnvironmentVnet
- ** API Client** (2018-02-01): POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/moveResources
- ** API Client** (2018-02-01): POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/validateContainerSettings
- ** API Client** (2018-02-01): POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/validateMoveResources
- ** API Client** (2018-02-01): PUT /providers/Microsoft.Web/publishingUsers/web
- ** API Client** (2018-02-01): PUT /providers/Microsoft.Web/sourcecontrols/{sourceControlType}
- ** Seller Service Metrics API ** (1.2.0): GET /customer_service_metric/{customer_service_metric_type}/{evaluation_type}
- ** Seller Service Metrics API ** (1.2.0): GET /customer_service_metric/{customer_service_metric_type}/{evaluation_type}
- ** Seller Service Metrics API ** (1.2.0): GET /seller_standards_profile
- ** Seller Service Metrics API ** (1.2.0): GET /seller_standards_profile
- ** Seller Service Metrics API ** (1.2.0): GET /seller_standards_profile/{program}/{cycle}
- ** Seller Service Metrics API ** (1.2.0): GET /seller_standards_profile/{program}/{cycle}
- ** Seller Service Metrics API ** (1.2.0): GET /traffic_report
- ** Seller Service Metrics API ** (1.2.0): GET /traffic_report
- **1,000,000+ Recipe and Grocery List API (v2)** (partner): DELETE /grocerylist

## Accuracy & Terms
- Accuracy is best-effort. Verify against the primary source before safety-critical or production use.
- Full terms: /terms · Privacy: /privacy
- Found an error? POST /api/v1/report-error (free, no auth required)
- Human correction form: /report-error. Reports enter a private operator review queue and never return protected record data.

## Data Sources & Attribution
- **APIs.guru OpenAPI Directory** — CC-BY 4.0. OpenAPI specification metadata.
- **Publisher OpenAPI specifications** — Per publisher. Facts extracted; documents not redistributed.
- **Manufacturer datasheets** — © respective manufacturer. Factual parameters only; no datasheet text or diagrams reproduced.

## Agent API Endpoints
- GET /api/v1/components?q={query}&limit=20&format=compact
- GET /api/v1/components/:partNumber
- GET /api/v1/search/semantic?q={intent}
- GET /api/v1/apis?service={name}&q={query}&limit=20
- GET /api/v1/apis/:service/breaking-changes?fromVersion=&toVersion=
- GET /api/v1/apis/:service/brief?endpoint= — integration brief, everything needed for one working call
- GET /api/v1/apis/:service/deprecations — declared deprecations and sunset dates
- GET /api/v1/apis/auth-playbook?service= — auth schemes, scopes, rate-limit headers, error codes
- GET /api/v1/discover?q={capability} — which indexed service can do X
- GET /api/v1/packages/:registry/:name/advisory?from=&to= — what breaks between two npm or PyPI versions
- GET /api/v1/packages/stats (free)
- POST /api/v1/apis/watches/subscribe (Bearer key) — be told when a spec changes
- GET /api/v1/stats (free)
- GET /api/v1/pricing (free)
- GET /api/v1/balance (free, Bearer key) — remaining prepaid credit and trial credit
- GET /billing — human-facing top-up page (card payment)
- POST /mcp (Model Context Protocol, JSON-RPC 2.0)

## MCP
Streamable HTTP endpoint: POST /mcp · protocol 2025-06-18
Tools: factreason_package_upgrade_advisory, factreason_api_breaking_changes, factreason_api_schema, factreason_integration_brief, factreason_discover_api, factreason_create_key, factreason_create_topup_link, factreason_component_spec, factreason_deprecation_scan, factreason_auth_playbook, factreason_subscribe_spec_changes
Successful compacted tool calls include tokenMetrics: fullTokens, compactTokens, savedTokens, reductionPct, encoding. Compact and full responses have the same authorization and price.