API リファレンス

Source API

ユーザー持ち込み source を import / inspect / map / resolve して saved List へ渡す API contract です。

このページの内容17項目

Source API は、CSV などの持ち込み source を account-scoped artifact として保存し、row を canonical company_id に解決するための grouped contract です。

手順全体を進める場合は Source Import Workflow を使ってください。このページは HTTP API と CLI JSON contract の確認用です。

契約サマリー

Step	Method / Path	Credit	CLI equivalent
import	`POST /api/signal-foundry/sources/import`	消費しない	`sf source import ./companies.csv --name "<name>" --json`
inspect	`GET /api/signal-foundry/sources/{sourceId}/inspect`	消費しない	`sf source inspect <sourceId> --json`
map	`POST /api/signal-foundry/sources/{sourceId}/map`	消費しない	`sf source map <sourceId> --entity company --column name=<header> --json`
resolve	`POST /api/signal-foundry/sources/{sourceId}/resolve`	matched row に Basic credit	`sf source resolve <sourceId> --execute --max-credits <n> --json`
review	`GET /api/signal-foundry/sources/{sourceId}/review`	消費しない	`sf source review <sourceId> --status multiple_candidates --json`
select	`POST /api/signal-foundry/sources/{sourceId}/select`	新規確定 row に 1 Basic credit	`sf source select <sourceId> --row <sourceRowId> --company <companyId> --max-credits 1 --json`

production は API key 必須です。Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY> か x-api-key: <SIGNAL_FOUNDRY_API_KEY> を使います。通常 accountId / account_id は送りません。

resolve と select は credit-consuming write なので、HTTP では Idempotency-Key と maxCredits、CLI では --execute --max-credits <n> --json を必ず付けます。

リクエスト

Import

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/import" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: source-import-20260501-001" \
  -d '{
    "name": "展示会リード",
    "originalFilename": "companies.csv",
    "contentSha256": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "headers": ["会社名", "法人番号", "URL"],
    "rows": [
      {
        "会社名": "株式会社サンプル",
        "法人番号": "1234567890123",
        "URL": "https://example.com"
      }
    ]
  }'

Inspect

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/inspect" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

Map

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/map" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "company",
    "columns": {
      "name": "会社名",
      "corporate_number": "法人番号",
      "domain": "URL"
    }
  }'

columns の key は corporate_number domain name ticker です。entity は現時点では company のみです。

Resolve

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/resolve" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: source-resolve-<sourceId>-001" \
  -d '{
    "execute": true,
    "maxCredits": 100
  }'

Review

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/review?status=multiple_candidates&limit=50" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

status は repeated または comma separated で送れます。主な値は matched multiple_candidates not_found invalid unresolved です。

Select

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/select" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: source-select-<sourceRowId>-001" \
  -d '{
    "row": "<sourceRowId>",
    "companyId": "jpx_1234",
    "maxCredits": 1
  }'

companyId は、その row の resolve_candidates[] に含まれる候補だけ指定できます。

レスポンス

共通 envelope

source endpoint は成功時に次の共通 key を返します。

{
  "ok": true,
  "command": "source.resolve",
  "status": "completed",
  "source": {
    "source_id": "<sourceId>",
    "status": "resolved",
    "row_count": 3,
    "headers": ["会社名", "法人番号", "URL"],
    "mapping": {
      "entity": "company",
      "columns": {
        "name": "会社名"
      }
    },
    "resolve_summary": {
      "matched": 2,
      "multiple_candidates": 1,
      "not_found": 0,
      "invalid": 0,
      "total": 3
    }
  },
  "next_actions": [
    "sf source review <sourceId> --status multiple_candidates --json"
  ]
}

Import / inspect / map

見る key:

source.source_id
source.row_count
source.headers
source.detected_identifier_columns
source.mapping
source.sample_rows
deduplicated
next_actions[]

Resolve

見る key:

source.resolve_summary.matched
source.resolve_summary.multiple_candidates
source.resolve_summary.not_found
resolution.matched
resolution.multiple_candidates
resolution.not_found
resolution.resolved_count
resolution.multiple_candidates_count
resolution.not_found_count
resolution.review_required_count
run.resolved_count
run.multiple_candidates_count
run.not_found_count
run.review_required_count
billing.credits_used
billing.max_credits
next_actions[]

run.*_count は agent 向けの stable count contract です。resolution.*_count は同じ値の互換 alias です。run.resolved_count は matched row 数、run.review_required_count は multiple_candidates / not_found / invalid / unresolved の合計です。件数は billing から推測しないでください。

Review

見る key:

review.statuses
review.total_reviewable_rows
review.unresolved_rows_remaining
rows[].source_row_id
rows[].resolve_status
rows[].resolve_candidates
rows[].candidate_count
rows[].needs_human

multiple_candidates は canonical data へ自動昇格しません。agent は rows[].resolve_candidates を人間に見せ、明示された候補だけ select します。

Select

見る key:

selected.source_row_id
selected.company_id
selected.candidate
billing.credits_used
billing.deduplicated
review.multiple_candidates_remaining
next_actions[]

同じ row / company / idempotency key の再試行では二重消費しません。

row status lifecycle

Status	Meaning	Next
`unresolved`	import 済みだが resolve 前	`map` 後に `resolve`
`matched`	canonical `company_id` に確定済み	saved List 作成へ進める
`multiple_candidates`	候補が複数あり人間確認が必要	`review` して `select`
`not_found`	identifier から候補が見つからない	source column を増やして map / resolve
`invalid`	row shape や mapping value が不正	source row を修正して再 import

復旧方法

Error code	Where	復旧
`invalid_source_headers` / `duplicate_source_headers`	import	headers を空・重複なしに直して再 import
`source_row_limit_exceeded`	import	source を分割して import
`empty_source_mapping`	map	`--column <field>=<header>` を少なくとも 1 つ指定
`source_mapping_required`	resolve	`sf source map <sourceId> --entity company ... --json` を先に実行
`execute_required`	resolve	body に `execute: true`、CLI に `--execute` を付ける
`idempotency_key_required`	resolve / select	`Idempotency-Key` header を付けて再試行
`max_credits_required`	resolve	`maxCredits` または `--max-credits <n>` を付ける
`max_credits_exceeded`	resolve / select	row を分割するか、見積もり以上の `maxCredits` にする
`source_row_not_selectable`	select	`multiple_candidates` の row だけ select する
`candidate_not_found`	select	`resolve_candidates[]` に含まれる `company_id` を指定する
`account_scope_conflict`	all	API key account と body / query の account 指定を一致させる。通常は account を送らない

credit_balance_insufficient が出た場合は、sf credits balance --json または GET /credits/balance で今実行できるかを確認してください。

手順全体を確認する: Source Import Workflow
saved List 化後の API を確認する: リストAPI
credit ledger を確認する: GET /credits

API リファレンス

Source API

ユーザー持ち込み source を import / inspect / map / resolve して saved List へ渡す API contract です。

このページの内容17項目

Source API は、CSV などの持ち込み source を account-scoped artifact として保存し、row を canonical company_id に解決するための grouped contract です。

手順全体を進める場合は Source Import Workflow を使ってください。このページは HTTP API と CLI JSON contract の確認用です。

契約サマリー

Step	Method / Path	Credit	CLI equivalent
import	`POST /api/signal-foundry/sources/import`	消費しない	`sf source import ./companies.csv --name "<name>" --json`
inspect	`GET /api/signal-foundry/sources/{sourceId}/inspect`	消費しない	`sf source inspect <sourceId> --json`
map	`POST /api/signal-foundry/sources/{sourceId}/map`	消費しない	`sf source map <sourceId> --entity company --column name=<header> --json`
resolve	`POST /api/signal-foundry/sources/{sourceId}/resolve`	matched row に Basic credit	`sf source resolve <sourceId> --execute --max-credits <n> --json`
review	`GET /api/signal-foundry/sources/{sourceId}/review`	消費しない	`sf source review <sourceId> --status multiple_candidates --json`
select	`POST /api/signal-foundry/sources/{sourceId}/select`	新規確定 row に 1 Basic credit	`sf source select <sourceId> --row <sourceRowId> --company <companyId> --max-credits 1 --json`

resolve と select は credit-consuming write なので、HTTP では Idempotency-Key と maxCredits、CLI では --execute --max-credits <n> --json を必ず付けます。

リクエスト

Import

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/import" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: source-import-20260501-001" \
  -d '{
    "name": "展示会リード",
    "originalFilename": "companies.csv",
    "contentSha256": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "headers": ["会社名", "法人番号", "URL"],
    "rows": [
      {
        "会社名": "株式会社サンプル",
        "法人番号": "1234567890123",
        "URL": "https://example.com"
      }
    ]
  }'

Inspect

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/inspect" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

Map

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/map" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "company",
    "columns": {
      "name": "会社名",
      "corporate_number": "法人番号",
      "domain": "URL"
    }
  }'

columns の key は corporate_number domain name ticker です。entity は現時点では company のみです。

Resolve

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/resolve" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: source-resolve-<sourceId>-001" \
  -d '{
    "execute": true,
    "maxCredits": 100
  }'

Review

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/review?status=multiple_candidates&limit=50" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

status は repeated または comma separated で送れます。主な値は matched multiple_candidates not_found invalid unresolved です。

Select

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/sources/<sourceId>/select" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: source-select-<sourceRowId>-001" \
  -d '{
    "row": "<sourceRowId>",
    "companyId": "jpx_1234",
    "maxCredits": 1
  }'

companyId は、その row の resolve_candidates[] に含まれる候補だけ指定できます。

レスポンス

共通 envelope

source endpoint は成功時に次の共通 key を返します。

{
  "ok": true,
  "command": "source.resolve",
  "status": "completed",
  "source": {
    "source_id": "<sourceId>",
    "status": "resolved",
    "row_count": 3,
    "headers": ["会社名", "法人番号", "URL"],
    "mapping": {
      "entity": "company",
      "columns": {
        "name": "会社名"
      }
    },
    "resolve_summary": {
      "matched": 2,
      "multiple_candidates": 1,
      "not_found": 0,
      "invalid": 0,
      "total": 3
    }
  },
  "next_actions": [
    "sf source review <sourceId> --status multiple_candidates --json"
  ]
}

Import / inspect / map

見る key:

source.source_id
source.row_count
source.headers
source.detected_identifier_columns
source.mapping
source.sample_rows
deduplicated
next_actions[]

Resolve

見る key:

source.resolve_summary.matched
source.resolve_summary.multiple_candidates
source.resolve_summary.not_found
resolution.matched
resolution.multiple_candidates
resolution.not_found
resolution.resolved_count
resolution.multiple_candidates_count
resolution.not_found_count
resolution.review_required_count
run.resolved_count
run.multiple_candidates_count
run.not_found_count
run.review_required_count
billing.credits_used
billing.max_credits
next_actions[]

Review

見る key:

review.statuses
review.total_reviewable_rows
review.unresolved_rows_remaining
rows[].source_row_id
rows[].resolve_status
rows[].resolve_candidates
rows[].candidate_count
rows[].needs_human

multiple_candidates は canonical data へ自動昇格しません。agent は rows[].resolve_candidates を人間に見せ、明示された候補だけ select します。

Select

見る key:

selected.source_row_id
selected.company_id
selected.candidate
billing.credits_used
billing.deduplicated
review.multiple_candidates_remaining
next_actions[]

同じ row / company / idempotency key の再試行では二重消費しません。

row status lifecycle

Status	Meaning	Next
`unresolved`	import 済みだが resolve 前	`map` 後に `resolve`
`matched`	canonical `company_id` に確定済み	saved List 作成へ進める
`multiple_candidates`	候補が複数あり人間確認が必要	`review` して `select`
`not_found`	identifier から候補が見つからない	source column を増やして map / resolve
`invalid`	row shape や mapping value が不正	source row を修正して再 import

復旧方法

Error code	Where	復旧
`invalid_source_headers` / `duplicate_source_headers`	import	headers を空・重複なしに直して再 import
`source_row_limit_exceeded`	import	source を分割して import
`empty_source_mapping`	map	`--column <field>=<header>` を少なくとも 1 つ指定
`source_mapping_required`	resolve	`sf source map <sourceId> --entity company ... --json` を先に実行
`execute_required`	resolve	body に `execute: true`、CLI に `--execute` を付ける
`idempotency_key_required`	resolve / select	`Idempotency-Key` header を付けて再試行
`max_credits_required`	resolve	`maxCredits` または `--max-credits <n>` を付ける
`max_credits_exceeded`	resolve / select	row を分割するか、見積もり以上の `maxCredits` にする
`source_row_not_selectable`	select	`multiple_candidates` の row だけ select する
`candidate_not_found`	select	`resolve_candidates[]` に含まれる `company_id` を指定する
`account_scope_conflict`	all	API key account と body / query の account 指定を一致させる。通常は account を送らない

credit_balance_insufficient が出た場合は、sf credits balance --json または GET /credits/balance で今実行できるかを確認してください。

手順全体を確認する: Source Import Workflow
saved List 化後の API を確認する: リストAPI
credit ledger を確認する: GET /credits

Source API

ユーザー持ち込み source を import / inspect / map / resolve して saved List へ渡す API contract です。

契約サマリー

リクエスト

Import

Inspect

Map

Resolve

Review

Select

レスポンス

共通 envelope

Import / inspect / map

Resolve

Review

Select

row status lifecycle

復旧方法

Next

Source API

ユーザー持ち込み source を import / inspect / map / resolve して saved List へ渡す API contract です。

契約サマリー

リクエスト

Import

Inspect

Map

Resolve

Review

Select

レスポンス

共通 envelope

Import / inspect / map

Resolve

Review

Select

row status lifecycle

復旧方法

Next