API リファレンス

Signal Foundry API は、会社データ、観測データ、保存済み List、source import、research item、credit ledger を既存システムへ組み込むための HTTP surface です。

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

endpoint の公開範囲、auth、credit tag、CLI equivalent は OpenAPI Endpoint Inventory を見ます。source と evidence の出所は Data 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 scope

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

HTTP API を直接使う場合も、request body や query に account を指定しないでください。API key account と request account が衝突した場合は 400 account_scope_conflict です。

Rate limit と usage

API key request は usage event と rate limit の対象です。

current default:

超過時は 429 rate_limit_exceeded と Retry-After header を返します。

Credit boundary

request usage と product credit は別物です。

credit-consuming write は、必ず execute: true と maxCredits を付けます。CLI では --execute --max-credits <n> です。

operation ごとの正本は Credit Schedule です。

現行 surface の確認

API endpoint や filter は docs より実装が先に変わることがあります。組み込み前に、CLI と capability contract を確認してください。

sf data capabilities --json
sf --help
sf list --help

見る key:

• contract_version
• capabilities[].source_id
• capabilities[].status
• capabilities[].filters[]
• capabilities[].entrypoints[]
• capabilities[].pricing
• capabilities[].limitations[]

網羅的な現況は Data Capability Map に寄せています。

Public endpoint map

Company read

Cross-company search

List workspace

Saved list operations

delivery は saved List の handoff surface です。approval workflow、CRM sync、full monitor / alert を agent が勝手に始める surface ではありません。

Discovery runs

Source import

Research / job artifacts / feedback / credits

ID 解決

companyId は canonical company_id を推奨します。

よく使う値:

• jpx_7203
• 7203
• corporate number
• normalized company name
• website domain

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

sf companies identity KEYENCE --json
sf companies search 7203 --json

見る key:

• identity.company_id
• identity.matched_by
• candidates[].candidate_rank_reason
• companies[].company.company_id
• companies[].query_match
• meta.returned_companies

filingId は、edinet_fil_* の filing_id か EDINET doc_id を使えます。比較前に sf company filings <companyId> --json で選び、必要なら sf filing show <companyId> <filingId> --json で artifact_health / fact_stats / segment_metrics を確認します。

共通 response の読み方

成功 response は endpoint ごとに違いますが、agent はまず次の種類の 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 companies search 7203 --json
sf credits balance --json

list workflow なら:

sf list estimate "上場企業のうち、売上100億以上" --json
sf list candidates --from-estimate <estimateId> --json
sf list materialize --from-estimate <estimateId> --execute --max-credits <n> --json

OpenAPI について

OpenAPI は external integration / SDK generation には有効です。ただし現時点では、CLI JSON contract と docs の recovery path を先に正本にします。

OpenAPI 化の前に整理すること:

• endpoint visibility と auth / credit boundary を固定する
• route-local Zod schema を export 可能にする
• success response schema の owner を決める
• auth / rate / credit tag taxonomy を固定する
• /llms.txt と API reference の重複を整理する

endpoint inventory は OpenAPI Endpoint Inventory に固定します。この backlog は Docs Map の方針に従って管理します。