API リファレンス

リストAPI

saved List を作る API sequence の入口です。estimate / candidates / materialize / enrichment / export の順番と credit boundary をまとめます。

このページの内容7項目

List API は、会社候補を保存前に見積もり、preview し、明示的な credit cap 付きで saved List に変え、必要なら enrichment と export へ進める HTTP surface です。

agent から使う場合は、まず CLI を使ってください。HTTP API は、既存システムから直接組み込む場合の contract です。

契約サマリー

Phase	Endpoint	Credit	CLI	Detail
見積もり	`POST /lists/estimate`	消費しない	`sf list estimate "<query>" --json`	Lists Estimate
候補確認	`GET /lists/candidates`	消費しない	`sf list candidates --from-estimate <estimateId> --json`	Lists Candidates
保存	`POST /lists/materialize`	Basic row 分	`sf list materialize --from-estimate <estimateId> --execute --max-credits <n> --json`	Lists Materialize
enrichment	`POST /lists/{listId}/enrichments/*`	found row 分	`sf list enrich <listId> --source website --estimate --json`	Lists Enrichments
export	`GET /lists/{listId}/export`	消費しない	`sf list export <listId> --format csv --output ./list.csv --json`	Lists Export

production は API key 必須です。API key に紐づく account が保存先になります。通常の public API request では account_id / accountId を送りません。

リクエスト

推奨 sequence:

POST /api/signal-foundry/lists/estimate
-> GET /api/signal-foundry/lists/candidates?estimate_id=<estimateId>
-> POST /api/signal-foundry/lists/materialize
-> POST /api/signal-foundry/lists/{listId}/enrichments/estimate
-> POST /api/signal-foundry/lists/{listId}/enrichments/run
-> GET /api/signal-foundry/lists/{listId}/export

最初に CLI で同じ sequence を確認する場合:

sf list estimate "上場企業のうち、売上100億以上" --json
sf list candidates --from-estimate <estimateId> --json
sf list materialize --from-estimate <estimateId> --name "売上100億以上の上場企業" --execute --max-credits <estimatedCredits> --json
sf list enrich <listId> --source website --estimate --json
sf list enrich <listId> --source website --execute --max-credits <estimatedMaxCredits> --json
sf list export <listId> --format csv --output ./exports/list.csv --json

レスポンス

この sequence で見る主要 artifact:

Artifact	Created by	Meaning
`estimate.estimate_id`	estimate	保存前の frozen plan
`companies[]`	candidates	preview。保存も export もされない
`list.list_id`	materialize	saved List
`run.run_id`	enrichment run	enrichment execution
`path` / `row_count` / `sha256`	export	CSV output metadata

Credit Boundary

Operation	Credit behavior	Required guard
estimate	消費しない	`billing.materialize.estimated_credits` を確認
candidates	消費しない	preview は export できない
materialize	saved row の Basic credit	`execute: true`, `maxCredits`, `Idempotency-Key`
enrichment estimate	消費しない	`estimate.estimated_max_credits` を確認
enrichment run	found row の enrichment credit	`execute: true`, `maxCredits`, `Idempotency-Key`
export	消費しない	saved List のみ

weak / unsupported 条件を 0 件成功として保存しないでください。保存前に resolved_definition、unsupported_conditions、weak_conditions を確認します。

エラー

共通 error:

Code	Recovery
`estimate_not_found`	Lists Estimate から再実行
`max_credits_required`	`maxCredits` を付けて再実行
`max_credits_exceeded`	query を狭めるか、見積もり以上の `maxCredits` を指定
`credit_balance_insufficient`	GET /credits/balance を確認
`preview_export_not_allowed`	Lists Materialize の後に export

API error envelope の共通形は API overview を見てください。

Saved List Operations

次の endpoint は saved List の read、snapshot、refresh、diff、review、handoff で使います。新しい会社リスト作成の正面導線は引き続き estimate -> candidates -> materialize です。

Endpoint	CLI	用途
`GET /lists`	`sf list ls --json`	saved List 一覧
`POST /lists`	`sf list create "<name>" --json`	空の List または source 由来 List を作る
`GET /lists/{listId}`	`sf list show <listId> --json`	List detail
`GET /lists/{listId}/preview`	`sf list preview <listId> --json`	publish 前の preview
`POST /lists/{listId}/publish`	`sf list publish <listId> --json`	published snapshot 作成
`POST /lists/{listId}/refresh`	`sf list refresh <listId> --json`	published definition の再評価
`GET /lists/{listId}/diffs/latest`	`sf list diff <listId> --json`	latest diff
`PATCH /lists/{listId}/status`	API only	`active` / `paused` / `archived`
`PATCH /lists/{listId}/schedule`	API only	`manual` / `daily` / `weekly`
`GET/PATCH /lists/{listId}/suppressions`	API only	row suppression
`PATCH /lists/{listId}/diff-rows/{diffRowId}/review`	API only	diff row review outcome
`PATCH /lists/{listId}/diff-rows/{diffRowId}/exclusion`	API only	diff row exclusion
`GET/PATCH /lists/{listId}/workspace-preferences`	API only	workspace preferences
`PATCH /lists/{listId}/delivery`	API only	Slack / webhook delivery handoff 設定
`POST /lists/{listId}/deliver`	API only	delivery handoff 実行

delivery は saved List handoff です。approval workflow、full monitor / alert、CRM sync を自動で始めるものではありません。

GET /lists/{listId}/preview / sf list preview は saved List row を rows[] に返します。companies[] は既存 agent との互換 alias です。agent は件数確認に meta.returned_rows を使います。

次に進む

保存前に見積もる: Lists Estimate
preview を確認する: Lists Candidates
saved List を作る: Lists Materialize
website enrichment を足す: Lists Enrichments
CSV を出す: Lists Export