apifacts

apifacts

A verified changelog of reality for AI agents. An open registry of typed, dated facts about what third-party machine interfaces (HTTP APIs, SDK packages, CLIs) actually do today, as opposed to what their docs say.

Why

Interfaces change, docs lag, and nobody tells the agent. Every session pays tokens to rediscover the same traps: a 200 with an empty array instead of a 429, a rate limit reported as status: 0 in the body, an SDK release that silently dropped a field. Documentation tools answer "give me the right docs"; apifacts answers "the docs are wrong about this endpoint right now, here is the verified difference".

Install

pip install apifacts-pytest   # pytest plugin: a test failing on an HTTP error prints the known facts
uvx apifacts check https://api.stripe.com/v1/charges -X GET --status 401   # CLI (and library)
npx skills add Illouminus/apifacts   # agent skill: on an API error, ask the registry first

Both packages are on PyPI, carry the same version and ship together from one tag (release). The plugin sends nothing until a test fails. The skill (skills/apifacts/SKILL.md) tells Claude Code and other agents when to call apifacts check and how to read the answer.

MCP

One tool, check(target, method, status, body), over stdio; no resources, no prompts. Claude Code:

claude mcp add apifacts -- uvx --from 'apifacts[mcp]' apifacts mcp

Claude Desktop, Cursor and other clients (mcpServers in their JSON config):

{"mcpServers": {"apifacts": {"command": "uvx", "args": ["--from", "apifacts[mcp]", "apifacts", "mcp"]}}}

apifacts mcp --offline answers from the snapshot packaged in the wheel and sends nothing.

How a fact is verified

• One fact per YAML file in facts/<service>/, with a kind (error_meaning, rate_limit, breaking_change, ...), the exact error signal, a one-sentence claim, dimensions (env, plan, region, account_state) and evidence.
• Truth comes only from deterministic probes: declarative HTTP steps and assertions that our runner executes on a schedule. No language model is called anywhere in the verification path.
• Fixes are data, not advice: members of a closed vocabulary with typed parameters (no free text, no shell, no foreign URLs), rendered to one English sentence by us.
• A probe in another environment never refutes a fact; it adds a dimension.

Calling check()

One endpoint answers and learns at the same time: the request is the contribution. Send the target and, optionally, the error you got; receive matching facts with typed fixes and what the probes observe. If the target matches a registered template, a normalized observation is stored (no bodies, headers, query strings or raw IPs).

curl -s https://apifacts.dev/v0/check \
  -H 'Content-Type: application/json' \
  -d '{"target": {"method": "POST", "url": "https://api.stripe.com/v1/payment_intents"},
       "error": {"status": 400, "body_excerpt": "Keys for idempotent requests can only be used with the same parameters they were first used with."}}'

The response is never empty: facts, observed, and an unknown.reason when nothing matches.

Status

The API is live at https://apifacts.dev (/v0/check, /v0/services, /openapi.json, /healthz; facts.baillot.dev, the old address, redirects there). The registry covers the services and facts listed at apifacts.dev/registry, each fact page showing how it was established; /llms.txt describes the API for agents. Design contracts live in docs/specs/.

Running your own copy: the API reads facts/ and services/ once, at startup, so after a git pull restart it; ops/deploy.sh checks out, syncs and restarts in one step.

Contributing

Calling check() is contributing. Pull requests are for humans and API producers: see CONTRIBUTING.md. Producer signatures are always free.

License

Code: MIT. Data (facts/ and the generated fact pages): CC BY 4.0.