API リファレンス

POST /feedback

CLI / Codex / Claude Code から feedback inbox へ要望や不具合を送る contract です。

このページの内容10項目

POST /api/signal-foundry/feedback は、要望・不具合・docs 改善を Signal Foundry 側の feedback inbox に送る endpoint です。

ユーザーに Canny 画面を直接触らせるのではなく、Web / CLI / Codex / Claude Code から要約済み feedback を送ります。raw transcript、API key、顧客秘密情報、非公開 URL は送らないでください。

契約サマリー

Field	Value
Method	`POST`
Path	`/api/signal-foundry/feedback`
Auth	production は API key 必須
Usage	request usage / rate limit 対象
Credit	消費しない
CLI	`sf feedback create "<title>" --details "<summary>" --source codex --json`

この endpoint の job は、明示された feedback を 1 件だけ作ることです。agent が憶測で feedback を増やしたり、会話全体を raw に送ったりしないでください。

リクエスト

HTTP

curl "https://signal-foundry.app/api/signal-foundry/feedback" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "保存済みリストにメモを付けたい",
    "details": "Codex から使っていて、list row ごとに短いメモを残したいです。",
    "kind": "feature",
    "source": "codex",
    "surface": "list.workspace"
  }'

CLI

sf feedback create "保存済みリストにメモを付けたい" \
  --details "Codex から使っていて、list row ごとに短いメモを残したいです。" \
  --source codex \
  --surface list.workspace \
  --json

リクエストボディ

Field	Required	Notes
`title`	Yes	`3..120` chars。1 feedback = 1 request に絞る
`details`	Yes	`10..5000` chars。要約済み内容だけを書く
`kind`	No	`feature` `bug` `docs` `other`。default `feature`
`source`	No	`cli` `codex` `claude` `web` `other`。default `cli`
`surface`	No	`list.workspace`, `companies.search` など
`errorCode`	No	関連する `error.code`
`version`	No	CLI / client version

CLI の --error-code や --details-file は CLI 側で errorCode / details に変換します。

レスポンス

見る key:

ok
command
status
request_id
account_id
api_usage_event_id
feedback.kind
feedback.source
feedback.surface
feedback.post_id
feedback.board_id
feedback.portal_url

例

{
  "ok": true,
  "command": "feedback.create",
  "mode": "execute",
  "status": "created",
  "request_id": "req_1234567890abcdef",
  "account_id": "00000000-0000-4000-8000-000000000000",
  "auth_mode": "api_key",
  "api_usage_event_id": "usage_123",
  "feedback": {
    "kind": "feature",
    "source": "codex",
    "surface": "list.workspace",
    "post_id": "canny_post_123",
    "board_id": "canny_board_123",
    "portal_url": "https://feedback.example.com"
  }
}

エラー

Code	Status	復旧
`authentication_required`	401	API key を付ける。CLI なら `sf auth setup` に戻る
`invalid_request`	400	`title` / `details` の長さ、`kind`、`source` を schema に合わせる
`account_scope_conflict`	400	API key 利用時は `accountId` を送らない
`feedback_not_configured`	503	Signal Foundry 側の設定問題。時間を置いて再送するか support に連絡する
`feedback_upstream_unavailable`	502	Canny API に到達できない。再送前に人間に確認する
`feedback_upstream_error`	4xx/5xx	Canny 側の error。重複投稿を避けるため再送前に確認する

復旧方法

feedback_not_configured が返る場合は、利用者側の CLI 設定では直せません。時間を置いて再送するか、support に連絡してください。CLI / agent に外部サービスの key を保存しないでください。

Canny 側の一時エラーで失敗した場合は、同じ feedback を再送できます。ただし、重複投稿にならないよう、agent は再送前に人間へ確認してください。

含めないもの

raw transcript の保存
API key / customer secret の保存
Canny board の管理
feedback から issue / roadmap への自動昇格