メインコンテンツへスキップ
このガイドでは、既存のインテグレーションを 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キーをサービスユーザーに置き換えます。
  1. Settings > Service users を開きます
  2. 適切なロールを持つサービスユーザーを作成します
  3. APIキー（cog_ で始まる）を生成します
  4. 既存の連携の設定を更新し、新しいキーを使用するようにします
# 変更前（レガシー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/sessionsPOST /v3/organizations/sessions
セッション一覧を取得GET /v1/sessionsGET /v3/organizations/sessions
セッションを取得GET /v1/session/{session_id}GET /v3/organizations/sessions/{devin_id}
メッセージを送信POST /v1/session/{session_id}/messagePOST /v3/organizations/sessions/{devin_id}/messages
セッションをアーカイブ—POST /v3/organizations/sessions/{devin_id}/archive
セッションを削除—DELETE /v3/organizations/sessions/{devin_id}

​
Knowledge エンドポイント

Operationv1 endpointCurrent endpoint
Knowledge の一覧取得GET /v1/knowledgeGET /v3/organizations/knowledge/notes
Knowledge の作成POST /v1/knowledgePOST /v3/organizations/knowledge/notes
Knowledge の更新PUT /v1/knowledge/{note_id}PUT /v3/organizations/knowledge/notes/{note_id}
Knowledge の削除DELETE /v1/knowledge/{note_id}DELETE /v3/organizations/knowledge/notes/{note_id}

​
Playbook エンドポイント

Operationv1/v2 endpointCurrent endpoint
Playbook 一覧取得GET /v1/playbooksGET /v3/organizations/playbooks
Playbook 作成POST /v1/playbooksPOST /v3/organizations/playbooks
Playbook 取得GET /v1/playbooks/{playbook_id}GET /v3/organizations/playbooks/{playbook_id}
Playbook 更新PUT /v1/playbooks/{playbook_id}PUT /v3/organizations/playbooks/{playbook_id}
Playbook 削除DELETE /v1/playbooks/{playbook_id}DELETE /v3/organizations/playbooks/{playbook_id}

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

操作v1 エンドポイント現在のエンドポイント
シークレット一覧取得GET /v1/secretsGET /v3/organizations/secrets
シークレット作成POST /v1/secretsPOST /v3/organizations/secrets
シークレット削除DELETE /v1/secrets/{secret_id}DELETE /v3/organizations/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/sessions?first=25"
# 次のページには、レスポンスの `end_cursor` を使用してください:
curl "https://api.devin.ai/v3/organizations/sessions?first=25&after=CURSOR_VALUE"
詳しくは Pagination を参照してください。

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

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

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

​
エラー応答

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

​
廃止スケジュール

レガシーAPIキーには、Devin の設定 UI に廃止予定のバナーが表示されます。移行期間中は次のように動作します。
  • 現在: レガシーAPIキーは引き続き利用できます。新しい組織では、レガシーキーを新規作成できない場合があります。
  • 廃止期間: レガシーキーとサービスユーザー トークンの両方を併用できます。
  • 提供終了: レガシーAPIキーはまもなく廃止されます。告知のため Devin の設定画面を確認してください。
ロールベースのアクセス制御、セッションの帰属管理、新機能を利用するため、できるだけ早くサービスユーザーへ移行することを推奨します。

​
お困りですか？

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