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

# API 概要

> Qoder Cloud Agents API の概要、ゲートウェイ URL、利用可能なリソース、リクエスト制限を紹介します。

## はじめに

Qoder Cloud Agents API は、クラウド AI Agent の包括的な管理機能を提供します。Agent の作成、環境設定、セッション管理、イベントストリーム処理などの主要機能をカバーします。すべての API は RESTful 設計に従い、リクエスト / レスポンス形式として JSON を使用します。

<Note>
  現在、API は Beta 段階にあり、一部の機能は今後のバージョンで調整される可能性があります。
</Note>

## ゲートウェイ URL

| 環境   | URL                                            |
| ---- | ---------------------------------------------- |
| 本番環境 | `https://api.qoder.com/api/api/v1/cloud/cloud` |

## バージョン

API は現在 `v1` バージョンです。すべてのエンドポイントは `/api/v1/cloud/` パスプレフィックスでバージョンを区別し、追加のバージョンヘッダーは不要です。

## 利用可能な API 一覧

| リソース                     | 説明                                                | ベースパス                                                       |
| ------------------------ | ------------------------------------------------- | ----------------------------------------------------------- |
| Agents                   | Agent インスタンスの作成・取得・更新・削除・アーカイブ                    | `/agents`                                                   |
| Environments             | 実行環境設定の管理                                         | `/environments`                                             |
| Sessions                 | Agent セッションの作成とライフサイクル管理                          | `/sessions`                                                 |
| Events                   | セッションイベントストリームの読み取りとプッシュ                          | `/events`                                                   |
| Files                    | ファイルのアップロードと関連付け管理                                | `/files`                                                    |
| Vaults                   | 機密認証情報の安全な保管                                      | `/vaults`                                                   |
| Skills                   | Agent Skill の登録と管理                                | `/skills`                                                   |
| Memory Stores            | 永続化されたメモリストア                                      | `/memory_stores`                                            |
| Deployments              | スケジュールデプロイメントの自動化                                 | `/deployments`                                              |
| Work                     | セルフホスト Environment の work キューと worker リースのライフサイクル | `/environments/{environment_id}/work`                       |
| Forward Templates        | Forward Agent テンプレートの定義・バージョン・アーカイブ・クローン          | `/api/v1/forward/templates`                                 |
| Forward Identities       | Forward アイデンティティの作成・有効化/無効化・削除と Agent 照会          | `/api/v1/forward/identities`                                |
| Forward Identity Configs | アイデンティティ単位のテンプレート設定と有効設定の照会                       | `/api/v1/forward/identities/{identity_id}/templates`        |
| Forward Channels         | Forward チャネルと QR セッションの管理                         | `/api/v1/forward/channels`、`/api/v1/forward/qr_sessions`    |
| Forward Sessions         | Forward セッションのライフサイクル・イベント・SSE ストリーム              | `/api/v1/forward/sessions`                                  |
| Forward Resources        | Forward 外部リソースの登録と一覧                              | `/api/v1/forward/resources`                                 |
| Forward Schedules        | Forward の定時タスクと実行記録の管理                            | `/api/v1/forward/schedules`、`/api/v1/forward/schedule_runs` |

## リクエストサイズ制限

* 1 回のリクエスト Body の最大値: **4 MB**
* 上限を超えるとサーバー側で Body が切り詰められ、JSON パースに失敗して `400 invalid_request_error`（message: "Request body must be valid JSON."）が返されます。

## リクエストヘッダー

すべての API リクエストには `Authorization` ヘッダーが必須です。`Content-Type` は推奨ですが必須ではありません。

```
Authorization: Bearer $QODER_PAT
Content-Type: application/json   # 推奨
```

## レート制限

API アプリケーション層では明示的なレート制限を実装していません。ゲートウェイ層のグローバル保護がリクエスト頻度を管理します。ゲートウェイ保護がトリガーされると HTTP 429 または 503 が返される場合があります。クライアント側では指数バックオフリトライと適度なリクエスト間隔を推奨します。

## Beta ステータスについて

1. API インターフェースは全体として安定していますが、シグネチャは今後のバージョンで微調整される可能性があります。
2. 新機能は新しい Beta 識別子としてリリースされます。
3. 本番環境ではバージョンの固定と互換性対応を行うことを推奨します。
4. 現在のすべての機能は、追加の Beta ヘッダーなしで利用可能です。

## 接続性のクイック検証

```bash theme={null}
# 現在のアカウント配下の Agent を一覧表示（認証と接続性の確認） \
curl -s https://api.qoder.com/api/v1/cloud/agents?limit=1 \
  -H "Authorization: Bearer $QODER_PAT"
```

成功時のレスポンス例:

```json theme={null}
{
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}
```

## 次のステップ

<CardGroup cols={3}>
  <Card title="認証" icon="key" href="/ja/cloud-agents/api/conventions/authentication">
    PAT の取得と利用。
  </Card>

  <Card title="エラーリファレンス" icon="triangle-exclamation" href="/ja/cloud-agents/api/conventions/errors">
    エラーコードとトラブルシューティング。
  </Card>

  <Card title="ページネーション" icon="list" href="/ja/cloud-agents/api/conventions/pagination">
    リスト API のページング。
  </Card>
</CardGroup>