API リファレンス

External Research API

company に紐づく外部調査 item の estimate / fetch / list contract です。

このページの内容12項目

External Research API は、会社に紐づく補助調査を canonical observation と分けて保存するための advanced HTTP contract です。通常の CLI 操作では Research Items API と sf research add / ls を使います。

この page の endpoints は、既存 backend から external research の credit estimate、fetch、list を直接組み込む場合に使います。canonical company profile や observations を自動更新する endpoint ではありません。

契約サマリー

Endpoint	Purpose	Credit	CLI equivalent
`POST /api/signal-foundry/research/external/estimate`	外部調査 item の credit 見積もり	無料	直接 CLI はなし。通常は `sf research add <companyId> --content-file ... --json`
`POST /api/signal-foundry/research/external/fetch`	外部調査 item を保存	estimate に応じて記録	`sf research add <companyId> --content-file ... --json`
`GET /api/signal-foundry/research/external`	account / company / list 単位で一覧取得	無料	`sf research ls --json`

production は API key 必須です。API key 利用時は accountId / account_id を送らず、key の account scope に任せてください。

リクエスト

Estimate

curl "https://signal-foundry.app/api/signal-foundry/research/external/estimate" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "jpx_7203",
    "job": "web_research",
    "sourceType": "manual",
    "resultCount": 1,
    "sourceCount": 1,
    "pageCount": 0
  }'

body fields:

Field	Required	Notes
`companyId`	No	canonical `company_id`。保存時は required
`listId`	No	saved List context
`job`	No	estimate job
`sourceType`	No	`crawl4ai` `web_search` `deep_search` `pdf_extract` `manual`
`resultCount`	No	default は service 側
`sourceCount`	No	default は service 側
`pageCount`	No	default は service 側

Fetch

curl "https://signal-foundry.app/api/signal-foundry/research/external/fetch" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "jpx_7203",
    "sourceType": "manual",
    "title": "IR補助メモ",
    "contentMarkdown": "公開IR資料を確認した補助メモです。",
    "sourceUrl": "https://example.com/research-note",
    "promotionStatus": "session_only",
    "estimate": {
      "job": "manual_note",
      "resultCount": 1,
      "sourceCount": 1,
      "pageCount": 0
    }
  }'

CLI equivalent:

sf research add jpx_7203 \
  --title "IR補助メモ" \
  --source-type manual \
  --content-file ./note.md \
  --json

body fields:

Field	Required	Notes
`companyId`	Yes	canonical `company_id`
`sourceType`	Yes	external research source type
`contentMarkdown`	No	markdown body
`title`	No	人間向け title
`sourceUrl`	No	public source URL。private URL は入れない
`promotionStatus`	No	`session_only` `reusable` `canonical_candidate` `promoted`
`dedupeKey`	No	重複保存を避ける key
`confidence`	No	`0..1`
`evidence` / `producer` / `structuredPayload`	No	JSON object
`observedAt` / `fetchedAt`	No	ISO datetime
`estimate`	No	credit estimate input
`listId`	No	saved List context

List

curl "https://signal-foundry.app/api/signal-foundry/research/external?company_id=jpx_7203&limit=20" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

CLI equivalent:

sf research ls --company-id jpx_7203 --json

query parameters:

Param	Type	Notes
`company_id`	string	company に紐づく item だけを見る
`list_id`	uuid	saved List に紐づく item だけを見る
`limit`	integer	default `20`, max `100`

レスポンス

Estimate response

見る key:

ok
estimate
meta.account_id
meta.auth_mode
meta.company_id
meta.list_id

Fetch response

見る key:

created
item
item.research_item_id
item.company_id
item.source_type
item.promotion_status
estimate
credit_event
meta.account_id
meta.auth_mode

List response

見る key:

items[]
items[].research_item_id
items[].company_id
items[].source_type
items[].promotion_status
items[].fetched_at
meta.account_id
meta.company_id
meta.list_id
meta.limit

エラー

Code	Status	復旧
`invalid_request`	400	body の required field と enum を確認する
`invalid_query`	400	`company_id`, `list_id`, `limit` を schema に合わせる
`account_scope_conflict`	400	API key 利用時は `accountId` / `account_id` を送らない
`company_not_found`	404	`sf companies search <query> --json` で canonical `company_id` を解決し直す
`credit_balance_insufficient`	402	`sf credits balance --json` で残高を確認する
`invalid_api_key`	401	API key を再発行し、CLI なら `sf auth setup` をやり直す

復旧方法

company_not_found が返る場合:

sf companies search <query> --json を実行します。
companies[].company.company_id を確認します。
解決した company_id で fetch を再実行します。

account_scope_conflict が返る場合は、API key と body / query の account scope が衝突しています。通常は accountId / account_id を送らず、API key から解決させてください。

含めないもの

canonical observation への自動 promotion
company-less research item の public workflow
queue / retry / schedule
raw transcript、API key、顧客秘密情報、private URL の保存

API リファレンス

External Research API

company に紐づく外部調査 item の estimate / fetch / list contract です。

このページの内容12項目

契約サマリー

Endpoint	Purpose	Credit	CLI equivalent
`POST /api/signal-foundry/research/external/estimate`	外部調査 item の credit 見積もり	無料	直接 CLI はなし。通常は `sf research add <companyId> --content-file ... --json`
`POST /api/signal-foundry/research/external/fetch`	外部調査 item を保存	estimate に応じて記録	`sf research add <companyId> --content-file ... --json`
`GET /api/signal-foundry/research/external`	account / company / list 単位で一覧取得	無料	`sf research ls --json`

production は API key 必須です。API key 利用時は accountId / account_id を送らず、key の account scope に任せてください。

リクエスト

Estimate

curl "https://signal-foundry.app/api/signal-foundry/research/external/estimate" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "jpx_7203",
    "job": "web_research",
    "sourceType": "manual",
    "resultCount": 1,
    "sourceCount": 1,
    "pageCount": 0
  }'

body fields:

Field	Required	Notes
`companyId`	No	canonical `company_id`。保存時は required
`listId`	No	saved List context
`job`	No	estimate job
`sourceType`	No	`crawl4ai` `web_search` `deep_search` `pdf_extract` `manual`
`resultCount`	No	default は service 側
`sourceCount`	No	default は service 側
`pageCount`	No	default は service 側

Fetch

curl "https://signal-foundry.app/api/signal-foundry/research/external/fetch" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "jpx_7203",
    "sourceType": "manual",
    "title": "IR補助メモ",
    "contentMarkdown": "公開IR資料を確認した補助メモです。",
    "sourceUrl": "https://example.com/research-note",
    "promotionStatus": "session_only",
    "estimate": {
      "job": "manual_note",
      "resultCount": 1,
      "sourceCount": 1,
      "pageCount": 0
    }
  }'

CLI equivalent:

sf research add jpx_7203 \
  --title "IR補助メモ" \
  --source-type manual \
  --content-file ./note.md \
  --json

body fields:

Field	Required	Notes
`companyId`	Yes	canonical `company_id`
`sourceType`	Yes	external research source type
`contentMarkdown`	No	markdown body
`title`	No	人間向け title
`sourceUrl`	No	public source URL。private URL は入れない
`promotionStatus`	No	`session_only` `reusable` `canonical_candidate` `promoted`
`dedupeKey`	No	重複保存を避ける key
`confidence`	No	`0..1`
`evidence` / `producer` / `structuredPayload`	No	JSON object
`observedAt` / `fetchedAt`	No	ISO datetime
`estimate`	No	credit estimate input
`listId`	No	saved List context

List

curl "https://signal-foundry.app/api/signal-foundry/research/external?company_id=jpx_7203&limit=20" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

CLI equivalent:

sf research ls --company-id jpx_7203 --json

query parameters:

Param	Type	Notes
`company_id`	string	company に紐づく item だけを見る
`list_id`	uuid	saved List に紐づく item だけを見る
`limit`	integer	default `20`, max `100`

レスポンス

Estimate response

見る key:

ok
estimate
meta.account_id
meta.auth_mode
meta.company_id
meta.list_id

Fetch response

見る key:

created
item
item.research_item_id
item.company_id
item.source_type
item.promotion_status
estimate
credit_event
meta.account_id
meta.auth_mode

List response

見る key:

items[]
items[].research_item_id
items[].company_id
items[].source_type
items[].promotion_status
items[].fetched_at
meta.account_id
meta.company_id
meta.list_id
meta.limit

エラー

Code	Status	復旧
`invalid_request`	400	body の required field と enum を確認する
`invalid_query`	400	`company_id`, `list_id`, `limit` を schema に合わせる
`account_scope_conflict`	400	API key 利用時は `accountId` / `account_id` を送らない
`company_not_found`	404	`sf companies search <query> --json` で canonical `company_id` を解決し直す
`credit_balance_insufficient`	402	`sf credits balance --json` で残高を確認する
`invalid_api_key`	401	API key を再発行し、CLI なら `sf auth setup` をやり直す

復旧方法

company_not_found が返る場合:

sf companies search <query> --json を実行します。
companies[].company.company_id を確認します。
解決した company_id で fetch を再実行します。

含めないもの

canonical observation への自動 promotion
company-less research item の public workflow
queue / retry / schedule
raw transcript、API key、顧客秘密情報、private URL の保存