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

# v1/v2 からの移行

> API v1 または v2 から現行 API への移行

このガイドでは、既存のインテグレーションを API v1 または v2 から現行の Organization および Enterprise API へ移行する方法を説明します。旧バージョンの API (v1 と v2) は非推奨期間中も引き続き利用できますが、新機能はすべて現行の API でのみ提供されます。

<div id="whats-changing">
  ## 変更点
</div>

| 項目           | v1/v2 (レガシー)                        | 現行API                                     |
| ------------ | ----------------------------------- | ----------------------------------------- |
| **認証**       | APIキー (`apk_user_` または `apk_` で始まる) | サービスユーザー トークン (`cog_` で始まる)               |
| **ベースURL**   | `/v1/*`, `/v2/*`                    | `/v3/organizations/*`, `/v3/enterprise/*` |
| **ページネーション** | オフセット方式 (`offset` + `limit`)        | カーソル方式 (`first` + `after`)                |
| **スコープ**     | フラット — すべてのエンドポイントが同一階層に存在          | 組織スコープおよび Enterprise スコープ                 |
| **権限**       | キーレベル (すべて許可するか、一切許可しないかのどちらか)      | ロールベース＋きめ細かな権限                            |

<div id="step-1-create-a-service-user">
  ## ステップ 1: サービスユーザーを作成する
</div>

既存のレガシーAPIキーをサービスユーザーに置き換えます。

1. **Settings > Service users** を開きます
2. 適切なロールを持つサービスユーザーを作成します
3. APIキー (`cog_` で始まる) を生成します
4. 既存の連携の設定を更新し、新しいキーを使用するようにします

```bash theme={null}
# 変更前（レガシーAPIキー）
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

# 変更後（サービスユーザートークン）
curl -H "Authorization: Bearer cog_YOUR_SERVICE_USER_KEY" ...
```

<Note>
  既存のレガシーAPIキーは、非推奨期間中も引き続き使用できます。移行は段階的に行えます。
</Note>

<div id="step-2-update-endpoint-urls">
  ## ステップ2: エンドポイント URL を更新する
</div>

<div id="session-endpoints">
  ### セッションエンドポイント
</div>

| 操作          | v1 エンドポイント                              | 現行エンドポイント                                                      |
| ----------- | --------------------------------------- | -------------------------------------------------------------- |
| セッションを作成    | `POST /v1/sessions`                     | `POST /v3/organizations/{org_id}/sessions`                     |
| セッション一覧を取得  | `GET /v1/sessions`                      | `GET /v3/organizations/{org_id}/sessions`                      |
| セッションを取得    | `GET /v1/session/{session_id}`          | `GET /v3/organizations/{org_id}/sessions/{devin_id}`           |
| メッセージを送信    | `POST /v1/session/{session_id}/message` | `POST /v3/organizations/{org_id}/sessions/{devin_id}/messages` |
| セッションをアーカイブ | —                                       | `POST /v3/organizations/{org_id}/sessions/{devin_id}/archive`  |
| セッションを削除    | —                                       | `DELETE /v3/organizations/{org_id}/sessions/{devin_id}`        |

<div id="knowledge-endpoints">
  ### Knowledge エンドポイント
</div>

| 操作              | v1 エンドポイント                       | 現行エンドポイント                                                     |
| --------------- | -------------------------------- | ------------------------------------------------------------- |
| Knowledge の一覧取得 | `GET /v1/knowledge`              | `GET /v3/organizations/{org_id}/knowledge/notes`              |
| Knowledge の作成   | `POST /v1/knowledge`             | `POST /v3/organizations/{org_id}/knowledge/notes`             |
| Knowledge の更新   | `PUT /v1/knowledge/{note_id}`    | `PUT /v3/organizations/{org_id}/knowledge/notes/{note_id}`    |
| Knowledge の削除   | `DELETE /v1/knowledge/{note_id}` | `DELETE /v3/organizations/{org_id}/knowledge/notes/{note_id}` |

<div id="playbook-endpoints">
  ### Playbook エンドポイント
</div>

| 操作            | v1/v2 endpoint                       | 現行エンドポイント                                                   |
| ------------- | ------------------------------------ | ----------------------------------------------------------- |
| Playbook 一覧取得 | `GET /v1/playbooks`                  | `GET /v3/organizations/{org_id}/playbooks`                  |
| Playbook 作成   | `POST /v1/playbooks`                 | `POST /v3/organizations/{org_id}/playbooks`                 |
| Playbook 取得   | `GET /v1/playbooks/{playbook_id}`    | `GET /v3/organizations/{org_id}/playbooks/{playbook_id}`    |
| Playbook 更新   | `PUT /v1/playbooks/{playbook_id}`    | `PUT /v3/organizations/{org_id}/playbooks/{playbook_id}`    |
| Playbook 削除   | `DELETE /v1/playbooks/{playbook_id}` | `DELETE /v3/organizations/{org_id}/playbooks/{playbook_id}` |

<div id="secret-endpoints">
  ### シークレットエンドポイント
</div>

| 操作         | v1 エンドポイント                       | 現行エンドポイント                                               |
| ---------- | -------------------------------- | ------------------------------------------------------- |
| シークレット一覧取得 | `GET /v1/secrets`                | `GET /v3/organizations/{org_id}/secrets`                |
| シークレット作成   | `POST /v1/secrets`               | `POST /v3/organizations/{org_id}/secrets`               |
| シークレット削除   | `DELETE /v1/secrets/{secret_id}` | `DELETE /v3/organizations/{org_id}/secrets/{secret_id}` |

<div id="enterprise-only-endpoints-new">
  ### Enterprise 専用エンドポイント (新規)
</div>

これらのエンドポイントには v1/v2 に対応するものはなく、現行の API でのみ利用できます。

* `GET /v3/enterprise/organizations` — Organization 一覧
* `GET /v3/enterprise/audit-logs` — 監査ログ
* `GET /v3/enterprise/consumption/*` — 利用状況および請求データ
* `GET /v3/enterprise/metrics/*` — 利用状況メトリクス
* `GET /v3/enterprise/members/users` — ユーザー管理
* `GET /v3/enterprise/roles` — ロール管理
* サービスユーザーのプロビジョニング、IP アクセスリスト、ACU 制限など

<div id="step-3-update-pagination">
  ## ステップ 3: ページネーションを更新する
</div>

現行 API では、オフセット方式ではなくカーソル方式のページネーションを使用しています。

```bash theme={null}
# 変更前 (v1/v2 オフセットベース)
curl "https://api.devin.ai/v1/sessions?offset=0&limit=25"

# 変更後 (カーソルベース)
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25"
# 次のページには、レスポンスの `end_cursor` を使用してください:
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25&after=CURSOR_VALUE"
```

詳しくは [Pagination](/ja/api-reference/concepts/pagination) を参照してください。

<div id="step-4-handle-response-format-changes">
  ## ステップ 4: レスポンス形式の変更に対処する
</div>

<div id="session-status-values">
  ### セッションステータス値
</div>

現在の API は、より詳細なステータス情報を返します。完全なスキーマについては、エンドポイントのリファレンスを参照してください。

<div id="error-responses">
  ### エラー応答
</div>

エラーの形式は一貫しています。HTTP ステータスコードとエラー詳細を含む JSON ボディで構成されます。

<div id="deprecation-timeline">
  ## 廃止スケジュール
</div>

レガシーAPIキーには、Devin の設定 UI に廃止予定のバナーが表示されます。移行期間中は次のように動作します。

* **現在**: レガシーAPIキーは引き続き利用できます。新しい組織では、レガシーキーを新規作成できない場合があります。
* **廃止期間**: レガシーキーとサービスユーザー トークンの両方を併用できます。
* **提供終了**: レガシーAPIキーはまもなく廃止されます。告知のため Devin の設定画面を確認してください。

ロールベースのアクセス制御、セッションの帰属管理、新機能を利用するため、できるだけ早くサービスユーザーへ移行することを推奨します。

<div id="need-help">
  ## お困りですか？
</div>

移行中に問題が発生した場合は、通常お使いの Devin のサポートチャネルからご連絡いただくか、[support@cognition.ai](mailto:support@cognition.ai) までお問い合わせください。