API リファレンス

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

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

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 を直接使う場合も、request body や検索条件に account を指定しないで ください。API key account と request account が衝突した場合は 400 account_scope_conflict です。

Rate limit と usage

API key request は 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、batch 上限、検索結果上限は増やしません。

Usage boundary

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

通常の Signal Foundry data endpoint は、呼び出しごとに 1 request credit を 使います。credits、usage、feedback などの確認・管理 endpoint は対象外です。 深い Signals や deferred の batch / bulk は追加の利用量単位を持ちます。ただし batch / bulk は v0 の通常公開 workflow ではありません。

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

現行機能の確認

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 company search --help --json
sf company profile --help --json

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

API pages

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

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

ID 解決

companyId は canonical company_id を推奨します。

よく使う値:

• jpx_7203
• 7203
• corporate number
• normalized 会社 name
• website domain

1 社 API に入る前に、次で候補を固定してください。

sf company search KEYENCE --json
sf company 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 / IR Signals を読み、根拠 ID や artifact 状態が必要な場合だけ sf company filings <companyId> --json で確認します。

共通 response の読み方

成功 response は 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 --card --json
sf credits balance --json

OpenAPI について

OpenAPI は deferred です。

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