apifacts

apifacts

AI エージェントのための、検証済みの現実の変更履歴です。 サードパーティの機械向けインターフェース（HTTP API、SDK パッケージ、CLI）が、ドキュメントに書かれている内容ではなく、今日実際にどう動作するかを示す、型付きで日付のある事実を集めたオープンなレジストリです。

理由

インターフェースは変わり、ドキュメントは遅れ、エージェントには誰も知らせてくれません。セッションのたびに、同じ落とし穴を再発見するためにトークンを消費します。たとえば、429 の代わりに空の配列を返す 200、本文で status: 0 として報告されるレート制限、フィールドをひそかに削除した SDK のリリースなどです。ドキュメントツールが答えるのは「正しいドキュメントを教えて」ですが、apifacts が答えるのは「このエンドポイントについて、今のドキュメントは間違っています。検証済みの差異はこちらです」です。

インストール

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

どちらのパッケージも PyPI で公開されており、同じバージョンを持ち、1 つのタグから一緒にリリースされます（リリース）。プラグインはテストが失敗するまで何も送信しません。スキル（skills/apifacts/SKILL.md）では、apifacts check を呼び出すタイミングと、回答の読み方を Claude Code やその他のエージェントに説明しています。

MCP

stdio 経由で check(target, method, status, body) を呼び出す 1 つのツールを提供します。リソースやプロンプトはありません。Claude Code の場合：

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

Claude Desktop、Cursor、その他のクライアントの場合（JSON 設定の mcpServers）：

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

apifacts mcp --offline は、wheel に同梱されたスナップショットを使って応答し、何も送信しません。

事実の検証方法

• facts/<service>/ の各 YAML ファイルに 1 つの事実を記録します。種類（error_meaning、rate_limit、breaking_change など）、正確なエラーシグナル、1 文で述べた主張、次元（env、plan、region、account_state）、証拠を含みます。
• 真実の根拠となるのは 決定論的なプローブだけです。宣言的な HTTP ステップとアサーションを定義し、ランナーがスケジュールに従って実行します。検証プロセスで言語モデルが呼び出されることはありません。
• 修正は アドバイスではなくデータです。閉じた語彙から選んだ、型付きパラメーターを持つ項目で構成します（自由記述、シェル、外部 URL は使用できません）。私たちが英語の 1 文にして表示します。
• 別の環境でのプローブによって事実が否定されることはありません。次元が追加されます。

check() の呼び出し

1 つのエンドポイントが応答と学習を同時に行います。リクエスト自体が貢献となります。ターゲットと、必要に応じて受け取ったエラーを送信すると、一致する事実、型付きの修正、プローブで確認された内容が返されます。ターゲットが登録済みのテンプレートに一致する場合、正規化された観測結果が保存されます（本文、ヘッダー、クエリ文字列、生の IP アドレスは保存されません）。

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."}}'

応答が空になることはありません。一致がない場合も、facts、observed、および unknown.reason が返されます。

ステータス

API は https://apifacts.dev で稼働中です（/v0/check、/v0/services、/openapi.json、/healthz。旧アドレスの facts.baillot.dev はこちらにリダイレクトされます）。レジストリには、apifacts.dev/registry に掲載されているサービスと事実が登録されており、各事実のページにはその確認方法が記載されています。エージェント向けの API 説明は /llms.txt をご覧ください。設計契約は docs/specs/ にあります。

独自のコピーを実行する場合：API は起動時に facts/ と services/ を一度だけ読み込みます。そのため、git pull の後に再起動してください。ops/deploy.sh を使えば、チェックアウト、同期、再起動を 1 ステップで実行できます。

貢献

check() を呼び出すことが貢献になります。プルリクエストは人間と API プロデューサー向けです。CONTRIBUTING.md をご覧ください。プロデューサーのシグネチャは常に無料です。

ライセンス

コード：MIT。データ（facts/ と生成された事実のページ）：CC BY 4.0。