v1/v2 からの移行

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

変更点

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

ステップ 1: サービスユーザーを作成する

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

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

# 変更前（レガシーAPIキー）
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

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

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

ステップ2: エンドポイント URL を更新する

セッションエンドポイント

操作	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}`

Knowledge エンドポイント

操作	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}`

Playbook エンドポイント

操作	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}`

シークレットエンドポイント

操作	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}`

Enterprise 専用エンドポイント (新規)

これらのエンドポイントには 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 制限など

ステップ 3: ページネーションを更新する

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

# 変更前 (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 を参照してください。

ステップ 4: レスポンス形式の変更に対処する

セッションステータス値

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

エラー応答

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

廃止スケジュール

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

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

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

お困りですか？

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

​変更点

​ステップ 1: サービスユーザーを作成する

​ステップ2: エンドポイント URL を更新する

​セッションエンドポイント

​Knowledge エンドポイント

​Playbook エンドポイント

​シークレットエンドポイント

​Enterprise 専用エンドポイント (新規)

​ステップ 3: ページネーションを更新する

​ステップ 4: レスポンス形式の変更に対処する

​セッションステータス値

​エラー応答

​廃止スケジュール

​お困りですか？

変更点

ステップ 1: サービスユーザーを作成する

ステップ2: エンドポイント URL を更新する

セッションエンドポイント

Knowledge エンドポイント

Playbook エンドポイント

シークレットエンドポイント

Enterprise 専用エンドポイント (新規)

ステップ 3: ページネーションを更新する

ステップ 4: レスポンス形式の変更に対処する

セッションステータス値

エラー応答

廃止スケジュール

お困りですか？