API リファレンス

Signal Foundry API は、会社検索、Company Card、会社別 Signals、Usage を既存 システムへ組み込むための HTTP 機能です。

Claude Code / Codex から操作する場合はまず CLI を使います。CLI は同じ API を 叩き、--json でエージェントが検証しやすい形に整えます。HTTP API は、自社の backend、管理画面、パートナー連携から直接呼ぶときに使います。

ChatGPT / Claude から使う場合は MCP 接続 を使います。MCP では API key を貼らず、ChatGPT / Claude 側の OAuth 接続で認証します。

API を直接使う場合も、まずこのページで認証、Usage 境界、エラーの見方を 確認します。根拠と provenance の扱いは データの出所 を見ます。

まず決めること

迷ったら、まず CLI の --json で 1 回成功させてから HTTP API に移してください。

認証

production は API key 必須です。送信方法はどちらか 1 つにしてください。

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/companies?q=7203" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

または:

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/companies?q=7203" \
  -H "x-api-key: <SIGNAL_FOUNDRY_API_KEY>"

両方を送る場合は一致している必要があります。不一致なら 400 api_key_conflict です。

Account 範囲

通常、account_id は送りません。API key に紐づく account が自動で使われます。

HTTP API を直接使う場合も、リクエストボディや検索条件に account を指定しないで ください。API key account と request account が衝突した場合は 400 account_scope_conflict です。

複数アカウントをまたぐ運用や、ログ上で範囲を明示したい場合だけ、次のどちらかで account を明示できます。

• x-account-id ヘッダー
• account_id クエリパラメータ

両方送る場合は一致が必須です。また、送った account は OAuth principal の membership または API key に紐づく account_id と一致している必要があります。 どちらかがずれると 400 account_scope_conflict になります。

Rate limit と usage

API key のリクエストは usage event、plan quota、rate limit の対象です。

現在の Company-first product quota(正本は 請求):

rate limit 超過時は 429 rate_limit_exceeded と Retry-After header を返します。product quota 超過時は daily_*_quota_exceeded または monthly_*_quota_exceeded を返します。Credit Pack は credit 残高だけを増やし、plan quota、RPM、検索結果上限は増やしません。

Usage 境界

request usage と product クレジットは別物ですが、API / CLI の data request も credit ledger に記録します。

通常の Signal Foundry data endpoint は、呼び出しごとに 1 request credit を 使います。credits、usage などの確認・管理 endpoint は対象外です。 credit-consuming Signals は追加の利用量単位を持ちます。

操作ごとの正本は クレジット表 です。

現行機能の確認

API endpoint や絞り込みはドキュメントより実装が先に変わることがあります。 組み込み前に、CLI help と API ドキュメントの対応を確認してください。

sf --help --json
sf query --help --json
sf search --help --json
sf company --help --json
sf signals --help --json
sf usage --help --json

通常のユーザー / エージェントワークフローでは、Company Search / Company Card / Signals / Usage のドキュメントと --help --json を正本にしてください。

API ページ

HTTP API を直接組み込む場合だけ、対象ページへ進みます。

旧 workspace 系 API は compatibility surface です。新規導線では、会社検索 JSON を自社 backend や agent 側で保存・整形してください。

ID 解決

companyId は canonical company_id を推奨します。

よく使う値:

• jpx_7203
• 7203
• 法人番号
• 正規化した会社名
• domain

1 社分の API を呼ぶ前に、次で候補を固定してください。

sf search KEYENCE --json
sf search 7203 --json

見る key:

• companies[].company.company_id
• companies[].query_match
• companies[].card
• meta.returned_companies

filingId は、edinet_fil_* の filing_id か EDINET doc_id を使えます。 通常 workflow では、まず Company Card / Signals を読み、根拠 ID や artifact 状態が必要な場合だけ sf signals <companyId> --json で確認します。

共通レスポンスの読み方

成功レスポンスは endpoint ごとに違いますが、エージェントはまず次の種類の key を見ます。

エラー

共通 error envelope:

{
  "error": {
    "code": "invalid_query",
    "message": "Invalid query parameters"
  }
}

主な code:

直接 API を使う前の smoke

HTTP API を実装に組み込む前に、同じ操作を CLI で通します。

sf version --json --check-update
sf auth show --json
sf search 7203 --json
sf company jpx_7203 --json
sf credits balance --json

OpenAPI について

OpenAPI は deferred です。

現時点では、CLI JSON、この API 概要、各 endpoint ページを正本にします。 SDK 生成や OpenAPI spec を前提にした実装は、公開されるまで待ってください。