Fast Insight API

調査の作成、募集の開始、結果の取得をプログラムから行うための API です。ベースパスは /api/public/v1 です。バージョン付きで、追加のみを行います（v1 の中でフィールドを削除したり、意味を変えたりすることはありません）。

認証

APIキーを x-api-key ヘッダーで送信してください。

curl https://fastinsight.ai/api/public/v1/studies \
  -H "x-api-key: fi_live_..."

キーは利用者単位です。キーは作成した本人として動作し、その方が Web アプリでアクセスできる範囲とまったく同じ範囲にのみアクセスできます。それ以上は行えません。

「組織単位のキー」を用意していないのはこのためです。Fast Insight では調査の編集権限は作成者と承諾済みの共同編集者（別の組織の方である場合もあります）に属し、組織の全員が持つわけではありません。組織単位のキーはこの区別を無視し、画面上では拒否される操作を API 経由で許してしまいます。

実務上の注意点：キーを作成した方が退職された場合は、そのキーを無効化し、在籍している方の権限で作り直してください。 アカウントが削除されると、そのキーは自動的に無効化されます。

キーの文字列が表示されるのは作成時の一度だけです。サーバーには SHA-256 のハッシュと先頭の数文字のみを保存しているため、紛失した場合は再表示ではなく、無効化して再作成してください。

権限（スコープ）

studies:write は意図的に募集開始を含みません。またパネル募集の開始には launch:byop に加えて launch:panel が必要です。これにより、調査を組み立てることはできても費用を発生させられない自動化を作ることができます。

エラー

{
  "error": "Study not found.",
  "code": "not_found",
  "requestId": "0f9c...",
  "issues": [{ "path": "numberOfResponses", "message": "Expected number" }]
}

処理の分岐には error ではなく code をご利用ください（error の文面は変わる可能性があります）。お問い合わせの際は requestId をお知らせください。issues は入力値の検証エラーのときにのみ含まれます。

認証の失敗は常に 401 invalid_api_key を返します。キーが未指定・形式不正・存在しない・無効化済みのいずれであっても、区別できないようにしてあります。アクセス権のないものは 403 ではなく 404 not_found を返すため、他の方の調査が存在するかどうかを API から知ることはできません。

レート制限

キーごと、1分あたり：読み取り 120回、書き込み 30回、負荷の高い呼び出し（募集開始、募集条件の提案）6回です。上限を超えると 429 と Retry-After を返します。

冪等性（Idempotency）

募集開始の呼び出しには Idempotency-Key を付けてください。同じキーで再送した場合は、二重に募集を開始せず、最初のレスポンスをそのまま返します。

curl -X POST .../studies/{id}/launch \
  -H "x-api-key: fi_live_..." \
  -H "Idempotency-Key: 6f1c..."

キーは呼び出し元・エンドポイント・対象の調査・リクエスト本文に紐づきます。同じキーで異なる本文を送った場合は、黙って前回の結果を返すのではなく 409 idempotency_key_reused を返します。記録は24時間で失効します。

ひとつ意図的な例外があります。募集は開始されたものの調査情報の確定に失敗した場合、キーは保持され、同じエラーが再生されます。この時点ですでに費用が発生しているため、再試行で募集処理に入り直してはならないからです。再試行ではなく、サポートまでご連絡ください。

エンドポイント

GET /studies

カーソル方式のページングです。limit（1〜100、既定 25）、cursor、status（DRAFT|ACTIVE|ARCHIVED）を指定できます。

{ "data": [ { "id": "...", "title": "...", "status": "ACTIVE" } ],
  "nextCursor": "eyJ..." }

nextCursor を次の cursor として渡してください。null は最終ページを表します。

POST /studies/{id}/launch

下書き（DRAFT）を ACTIVE に切り替え、募集を開始します。本文は任意で、指定した項目はその募集開始のときだけ保存値を上書きします。

{ "numberOfResponses": 30, "targetCountry": "JP", "interviewLanguage": "ja" }

回答者用のリンクを絶対 URL で返します。

{ "id": "...", "status": "ACTIVE", "recruitmentMode": "PANEL",
  "recruitLinks": [ { "groupId": "...", "label": "グループ1", "url": "https://..." } ] }

主なエラー：402 insufficient_credits（details に残高と不足額を含みます）、400 below_min_responses、400 feasibility_red（パネルの母数が不足しています）、409 study_busy（すでに募集開始の処理中です）、400 targeting_incomplete。

募集開始は Web アプリとまったく同じ処理を通ります。二重に募集が開始されることを防ぐ仕組みも共通です。

POST /studies

下書きを作成します。title、purpose、customerDefinition（対象条件または除外条件を1つ以上）が必須です。guide を渡すと、1回の呼び出しで募集開始できる状態の下書きになります。Idempotency-Key に対応しています。

本文の検証は厳格です。未知の項目は黙って無視せず、その項目名を挙げて 400 を返します。modality は VOICE または VIDEO、recruitmentMode の既定値は PANEL です。回答件数の指定は作成ではなく募集開始で行います。

ガイドの1項目は次の形です。id は UUID（画面のエディタが行ごとに発行します）、followUpDepth は数値ではなく列挙値です。

{
  "id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "part": 1,
  "order": 0,
  "question": "最近の買い物で、迷ってからやめた経験を教えてください。",
  "followUpDepth": "1",
  "followUpGuideline": ""
}

followUpDepth は none、if_short、1、2_3 のいずれかです。none と if_short の行は followUpGuideline を空文字列にしてください。サーバー側でも空にするため、送信したガイドと読み出したガイドが異なる場合があります。

GET / PATCH /studies/{id}

調査の取得と編集を行います。編集は下書きのみ対象です。画面上では募集開始後に編集できる項目もありますが、API から実施中の調査を変更することは意図的に許可していません。

POST /studies/{id}/targeting/suggest

パネル募集には cintProfileMappings が必要です。これはパネル提供事業者の内部的な設問 ID で表した属性条件で、手作業で書くことはできません。このエンドポイントがある理由です。年齢や性別などの一般的な条件を送ると、そのまま利用できる募集条件を返します。apply: true を指定すると調査に保存します。

対象者の条件が抽象的すぎて属性に対応づけられない場合は 502 feasibility_unavailable を返します。条件をより具体的にしてから再度お試しください。

GET /studies/{id}/responses および /responses/{responseId}

カーソル方式のページングです。一覧はリサーチャー向けの可視条件（スクリーンアウト、品質フィルタ対象、プレビューを除外）を用います。これはレポートの対象（完了のみ）より広い条件です。そのため調査の completedCount とこの一覧の件数は一致しないことがあり、これは仕様どおりです。

書き起こしの各発言は、言語を推測させずに明示します。

{ "contentJa": "…", "originalText": "…", "sourceLanguage": "ko" }

日本語のインタビューでは originalText は null です。削除のご依頼により匿名化された回答は、anonymized: true を返し、発言は含みません。

GET /studies/{id}/report

?format=json（既定）または ?format=markdown を指定します。Markdown は決定的なレンダリング結果で、回答者の発言を出典付きで含みます。LLM による再要約ではないため、リサーチャーが画面で見ている内容とずれることはありません。レポートが作成される件数に達するまでは 404 report_not_ready を返します。