API リファレンス

GET/POST /research/items

external research item を canonical company data と分離して保存・一覧する API contract です。

このページの内容10項目

/api/signal-foundry/research/items は、外部調査メモ、web search 結果、PDF 抽出結果などを external research artifact として保存する endpoint pair です。

research item は canonical company / observation を直接更新しません。canonical data に昇格させる候補は promotionStatus で示しますが、自動 promotion や review workflow はこの endpoint の範囲外です。

契約サマリー

Endpoint	Purpose	Auth	Credit	CLI equivalent
`GET /api/signal-foundry/research/items`	保存済み external research item を読む	production は API key 必須	消費しない	`sf research ls --json`
`POST /api/signal-foundry/research/items`	company に紐づく external research item を保存する	production は API key 必須	保存自体は product credit を消費しない	`sf research add <companyId> --content "..." --json`

現行 public contract では companyId が必須です。company-less / list-only research item は deferred surface なので、保存前に sf companies search <query> --json で canonical company_id を固定してください。

リクエスト

GET

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/research/items?company_id=jpx_7203&limit=20" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

CLI equivalent:

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

クエリパラメータ:

Param	Type	Default	Notes
`company_id`	string	`null`	canonical `company_id`
`list_id`	uuid	`null`	optional list context
`promotion_status`	array	`[]`	repeated parameter
`source_type`	array	`[]`	repeated parameter
`limit`	integer	`20`	`1..100`

POST

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/research/items" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "jpx_7203",
    "title": "IR note",
    "sourceType": "manual",
    "sourceUrl": "https://example.com/research-note",
    "contentMarkdown": "補助的な外部調査メモ",
    "promotionStatus": "session_only",
    "dedupeKey": "manual:jpx_7203:2026-05-01",
    "evidence": {
      "source": "manual review"
    }
  }'

CLI equivalent:

sf research add jpx_7203 --title "IR note" --content-file ./note.md --json

body fields:

Field	Required	Notes
`companyId`	Yes	canonical `company_id`
`contentMarkdown`	Yes	保存する external artifact 本文
`sourceType`	Yes	`crawl4ai` `web_search` `deep_search` `pdf_extract` `manual`
`title`	No	人間向け title
`sourceUrl`	No	外部 source URL。private URL は入れない
`listId`	No	saved List 文脈
`promotionStatus`	No	`session_only` `reusable` `canonical_candidate` `promoted`
`dedupeKey`	No	同じ artifact の重複保存を避ける key
`confidence`	No	`0..1`
`evidence` / `producer` / `structuredPayload`	No	JSON object
`observedAt` / `fetchedAt`	No	ISO datetime

レスポンス

GET response

見る key:

items[]
items[].research_item_id
items[].company_id
items[].title
items[].source_type
items[].source_url
items[].promotion_status
items[].content_markdown
items[].dedupe_key
items[].evidence
items[].structured_payload
items[].fetched_at
meta.filters
meta.returned_items

POST response

見る key:

item.research_item_id
item.company_id
item.source_type
item.promotion_status
item.content_markdown
item.source_url
item.dedupe_key
meta.created

meta.created=false の場合は、同じ dedupeKey の item がすでに存在しています。

エラー

Code	Status	復旧
`invalid_query`	400	`limit`、filter、repeated parameter を schema に合わせる
`invalid_request`	400	`companyId` `contentMarkdown` `sourceType` を確認する
`company_not_found`	404	`sf companies search <query> --json` で canonical `company_id` を解決し直す
`account_scope_conflict`	400	API key 利用時は `accountId` を送らない
`invalid_api_key`	401	API key を再発行し、CLI なら `sf auth setup` をやり直す

復旧方法

canonical data と external research の境界を保つため、外部調査を保存しても observations[] や company profile は更新された前提にしないでください。

canonical へ採用したい場合は promotionStatus: "canonical_candidate" として保存し、別の review / import process に渡します。company に紐付けられない artifact は、この public endpoint ではなく follow-up として扱います。

現時点で含めないもの

queue / retry / schedule
canonical observation への自動 promotion
company-less research item
raw transcript や private URL の保存

API リファレンス

GET/POST /research/items

external research item を canonical company data と分離して保存・一覧する API contract です。

このページの内容10項目

/api/signal-foundry/research/items は、外部調査メモ、web search 結果、PDF 抽出結果などを external research artifact として保存する endpoint pair です。

契約サマリー

Endpoint	Purpose	Auth	Credit	CLI equivalent
`GET /api/signal-foundry/research/items`	保存済み external research item を読む	production は API key 必須	消費しない	`sf research ls --json`
`POST /api/signal-foundry/research/items`	company に紐づく external research item を保存する	production は API key 必須	保存自体は product credit を消費しない	`sf research add <companyId> --content "..." --json`

リクエスト

GET

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/research/items?company_id=jpx_7203&limit=20" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>"

CLI equivalent:

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

クエリパラメータ:

Param	Type	Default	Notes
`company_id`	string	`null`	canonical `company_id`
`list_id`	uuid	`null`	optional list context
`promotion_status`	array	`[]`	repeated parameter
`source_type`	array	`[]`	repeated parameter
`limit`	integer	`20`	`1..100`

POST

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/research/items" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "jpx_7203",
    "title": "IR note",
    "sourceType": "manual",
    "sourceUrl": "https://example.com/research-note",
    "contentMarkdown": "補助的な外部調査メモ",
    "promotionStatus": "session_only",
    "dedupeKey": "manual:jpx_7203:2026-05-01",
    "evidence": {
      "source": "manual review"
    }
  }'

CLI equivalent:

sf research add jpx_7203 --title "IR note" --content-file ./note.md --json

body fields:

Field	Required	Notes
`companyId`	Yes	canonical `company_id`
`contentMarkdown`	Yes	保存する external artifact 本文
`sourceType`	Yes	`crawl4ai` `web_search` `deep_search` `pdf_extract` `manual`
`title`	No	人間向け title
`sourceUrl`	No	外部 source URL。private URL は入れない
`listId`	No	saved List 文脈
`promotionStatus`	No	`session_only` `reusable` `canonical_candidate` `promoted`
`dedupeKey`	No	同じ artifact の重複保存を避ける key
`confidence`	No	`0..1`
`evidence` / `producer` / `structuredPayload`	No	JSON object
`observedAt` / `fetchedAt`	No	ISO datetime

レスポンス

GET response

見る key:

items[]
items[].research_item_id
items[].company_id
items[].title
items[].source_type
items[].source_url
items[].promotion_status
items[].content_markdown
items[].dedupe_key
items[].evidence
items[].structured_payload
items[].fetched_at
meta.filters
meta.returned_items

POST response

見る key:

item.research_item_id
item.company_id
item.source_type
item.promotion_status
item.content_markdown
item.source_url
item.dedupe_key
meta.created

meta.created=false の場合は、同じ dedupeKey の item がすでに存在しています。

エラー

Code	Status	復旧
`invalid_query`	400	`limit`、filter、repeated parameter を schema に合わせる
`invalid_request`	400	`companyId` `contentMarkdown` `sourceType` を確認する
`company_not_found`	404	`sf companies search <query> --json` で canonical `company_id` を解決し直す
`account_scope_conflict`	400	API key 利用時は `accountId` を送らない
`invalid_api_key`	401	API key を再発行し、CLI なら `sf auth setup` をやり直す

復旧方法

canonical data と external research の境界を保つため、外部調査を保存しても observations[] や company profile は更新された前提にしないでください。

現時点で含めないもの

queue / retry / schedule
canonical observation への自動 promotion
company-less research item
raw transcript や private URL の保存