> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> Failproof AI Cloud の公開 `/v1` API に認証し、生成されたエンドポイントリファレンスを使用する方法。

公開 API は、Failproof AI ダッシュボードのオリジン上の `/v1` で提供されます。

## キーの作成とリクエストの実行

<Tabs>
  <Tab title="ダッシュボード">
    1. **管理 → キー** を開き、**キーの作成** を選択して、インテグレーションに必要な最小限のパーミッションプリセットを選びます。
    2. 必要な場合のみ個別の権限を追加し、キーを作成して、一度だけ表示されるシークレットをコピーします。
    3. `/v1/sessions` にテストリクエストを送信し、キーページでキーがアクティブであることを確認します。
    4. インテグレーションのオーナーが変わる際は、アクションメニューからキーのローテーションまたは無効化を行います。

           <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/key-create.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=a428bdae79f837471acb66414ff6455b" alt="パーミッションプリセットと個別権限が表示された新しい API キー作成ドロワー。" width="2940" height="1604" data-path="images/dashboard/key-create.png" />

    上図に作成ドロワーを示します。一度だけ表示されるシークレットは **作成** を選択した後にのみ表示されます。確認画面を閉じる前に必ずコピーしてください。
  </Tab>

  <Tab title="CLI">
    読み取り専用キーを作成し、`fp` または `curl` で直接使用します。

    ```bash theme={null}
    fp keys create reliability-reader \
      --permission-set read-only

    fp --api-key <key> sessions --since 24h
    ```

    ```bash theme={null}
    curl "https://app.befailproof.ai/v1/sessions?limit=20" \
      -H "Authorization: Bearer $FAILPROOFAI_KEY"
    ```
  </Tab>
</Tabs>

キーは組織とパーミッションセットにスコープされます。エンドポイントに必要なパーミッションを持たないリクエストは `403` を返し、不足しているパーミッションが通知されます。

## 組織の選択

組織キーは自動的にその組織に対して動作します。インスタンススコープのキーはリクエストごとに組織を選択できます。

<Tabs>
  <Tab title="ダッシュボード">
    **管理 → キー** を開く前に、ダッシュボードのヘッダーにある組織切り替えツールを使用します。そこで作成されたキーは選択した組織に属します。認証情報を自動化に組み込む前に、URL とキーの詳細で組織のスラッグを確認してください。
  </Tab>

  <Tab title="CLI">
    コマンドの前に `--org` を使用するか、インスタンススコープの API キーに対して組織ヘッダーを送信します。

    ```bash theme={null}
    fp orgs list
    fp --org reliability-team sessions --since 24h
    ```

    ```bash theme={null}
    curl "https://app.befailproof.ai/v1/usage" \
      -H "Authorization: Bearer $FAILPROOFAI_KEY" \
      -H "X-AgentEye-Org: reliability-team"
    ```
  </Tab>
</Tabs>

このセクションの生成されたエンドポイントページで、現在のパス、パラメーター、パーミッション要件、ステータスコードを確認してください。仕様はサーバーのルートアノテーションから生成され、`/v1` ルーターに対して検証されています。

現在の仕様はルート、メソッド、パラメーター、パーミッション、ステータスコードを網羅しています。一部のレスポンスボディは、サーバーが動的 JSON として構築しているため、意図的に型付けされていません。レスポンススキーマのないエンドポイントに対して厳密に型付けされたクライアントを生成する前に、実際のレスポンスを確認してください。

JSON の書き込みには `Content-Type: application/json` を使用してください。`401` は認証情報の欠如または無効を示し、`403` は有効な認証情報だが必要なパーミッションがないことを示します。`404` はリソースが存在しないか組織からアクセスできないことを、`409` は状態の競合を、`422` は無効なフィールドまたはパーミッション値を示します。エラーレスポンスには人間が読めるメッセージが含まれ、パーミッションエラーの場合は必要な権限も示されます。

<Warning>
  ポリシー適用のデプロイは、通常の公開 `/v1` サーフェスの外で意図的に管理されています。サポートされている Cloud デプロイワークフローを使用してください。
</Warning>