外部API連携

概要

Captain.AIは、パーソナルアクセストークン（PAT）を使用して外部からAPIにアクセスする機能を提供します。スクリプトや外部アプリケーションから、業務（エージェント）の実行や会話の作成を行えます。

注意: チャットAPIは非同期です。リクエストを受け付けた時点で応答が返り、AIの処理はバックグラウンドで進行します。チャット画面のようにAIの回答をAPIレスポンスとして受け取ることはできません。

パーソナルアクセストークン（PAT）の取得

APIにアクセスするには、まずPATを取得する必要があります。

手順

Captain.AIにログインします
設定 > アクセストークン を開きます
「新規作成」をクリックし、有効期限（30日 / 90日 / 365日 / 無期限）を選択します
生成されたトークン（cpt_ で始まる文字列）をコピーします

重要: トークンは作成時のみ表示されます。必ずコピーして安全な場所に保管してください。

PATとワークスペース

PATは発行時のワークスペースに束縛されます。

トークンは発行したワークスペースのデータ（業務・会話など）にのみアクセスできます
別のワークスペースで使いたい場合は、そのワークスペースに切り替えてから新しいトークンを発行してください
各トークンがどのワークスペースに紐づいているかは、設定 > アクセストークン の一覧で確認できます

ヒント: 正しいはずのIDに対して 404 Not Found が返る場合、PATが別のワークスペースで発行されている可能性があります。

エンドポイント一覧

PATで利用できるのは /api/external/ 配下のエンドポイントのみです（それ以外のAPIにPATでアクセスすると 403 になります）。

メソッド	パス	用途
POST	`/api/external/chat`	業務（エージェント）の会話を開始・継続する
GET	`/api/external/conversations`	自分の会話一覧を取得する（ページング対応）
POST	`/api/external/agent-goals`	業務を作成する
GET	`/api/external/agent-goals`	業務一覧を取得する
GET	`/api/external/agent-goals/{id}`	業務の詳細を取得する
GET	`/api/external/workers`	利用可能なワーカー一覧を取得する
GET	`/api/external/workers/{slug}`	ワーカーの詳細を取得する
GET	`/api/external/me`	自分のユーザー情報を取得する

認証

すべてのリクエストで、HTTPヘッダーにPATを含めます：

Authorization: Bearer cpt_xxxxxxxxxxxxxxxx

レート制限

POST /api/external/chat には、トークンごとに 60リクエスト/分 のレート制限があります。超過すると 429 Too Many Requests が返り、Retry-After ヘッダーで再試行までの秒数が通知されます。

チャットAPIの利用

エンドポイント

POST /api/external/chat

application/json と multipart/form-data（ファイル添付時）の両方に対応しています。

リクエストパラメータ

パラメータ	必須	説明
`agent_goal_id`	はい	使用する業務（エージェント）のID
`message`	条件付き	AIに送信するメッセージ。業務に「API使用」が有効なステップがある場合は省略可能（省略時はステップのコマンドのみ実行されます）
`conversation_id`	いいえ	既存の会話ID。指定すると同じ会話の続きとして送信されます。省略時は新しい会話が作成されます
`name`	いいえ	新規会話の表示名。省略時は「業務名_日付」の形式で自動命名されます
`files`	いいえ	添付ファイル（`multipart/form-data` 時のみ。複数指定可）

リクエスト例（テキストのみ）

curl -X POST https://<captain-ai-url>/api/external/chat \
  -H "Authorization: Bearer <your-personal-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "月次レポートを作成してください",
    "agent_goal_id": "<agent-goal-id>",
    "name": "月次レポート 8月"
  }'

リクエスト例（会話の継続）

curl -X POST https://<captain-ai-url>/api/external/chat \
  -H "Authorization: Bearer <your-personal-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "続きをお願いします",
    "agent_goal_id": "<agent-goal-id>",
    "conversation_id": "<conversation-id>"
  }'

リクエスト例（ファイル添付）

ファイルを添付する場合は、multipart/form-data 形式で送信します。

curl -X POST https://<captain-ai-url>/api/external/chat \
  -H "Authorization: Bearer <your-personal-access-token>" \
  -F "agent_goal_id=<agent-goal-id>" \
  -F "message=このファイルを分析してください" \
  -F "files=@/path/to/document.pdf" \
  -F "files=@/path/to/data.csv"

注意: 複数ファイルを添付する場合は、files フィールドを複数回指定します。

添付ファイルの制限

1ファイルあたり 100MB まで（音声・動画は 300MB まで）
1リクエスト全体で 110MB まで（超過時は 413）
対応形式: 文書（txt / md / csv / json / xlsx / docx / pptx / pdf など）、画像（png / jpg / gif / webp / svg）、音声・動画（mp3 / wav / mp4 / webm など）、コード（js / ts / py / sql など）。対応外の拡張子はエラーになります
アップロードされたファイルは、ワーカーセッションの input/ フォルダに保存されます

レスポンス

リクエストが受け付けられると 202 Accepted が返り、AIの処理はバックグラウンドで進行します。

{
  "conversation_id": "3f0c1234-....",
  "status": "processing",
  "content": "処理中です。完了までお待ちください。"
}

AIの回答内容はこのレスポンスには含まれません
処理結果はCaptain.AIの画面で該当の会話を開いて確認します
APIから進捗を知りたい場合は、GET /api/external/conversations を定期的に呼び、該当会話の message_count や last_message_at の変化を確認してください

主なエラー

コード	原因
`401`	トークンが無効・期限切れ・無効化済み
`403`	PATを `/api/external/` 以外に使用した、または業務・ワーカーへのアクセス権がない
`404`	業務・会話が存在しない、または別ワークスペースのPATでアクセスした
`422`	パラメータ不足（`agent_goal_id` 未指定、`message` もAPI用ステップもない等）
`429`	レート制限超過（`Retry-After` 秒後に再試行）
`503`	ワーカーが利用できない状態

業務作成APIの利用

外部システムから業務（エージェント）そのものを登録できます。

curl -X POST https://<captain-ai-url>/api/external/agent-goals \
  -H "Authorization: Bearer <your-personal-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "レポート自動生成",
    "worker_slug": "<worker-slug>",
    "goal": "受け取ったデータからレポートを生成する",
    "category_id": "<category-id>",
    "steps": [
      { "order": 1, "command": "init", "use_in_api": true }
    ]
  }'

成功時は 201 Created で作成された業務の情報が返ります
name（業務名）、steps（ステップ配列）、category_id（カテゴリID）が必須です
use_in_api: true を付けたステップは、チャットAPI呼び出し時に自動実行されます
環境変数（env_vars）は登録できますが、レスポンスには含まれません（秘匿情報のため）

活用例

CI/CDパイプラインからの利用

# ビルド結果をCaptainに報告
curl -X POST https://<captain-ai-url>/api/external/chat \
  -H "Authorization: Bearer $CAPTAIN_PAT" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"ビルド結果: ${BUILD_STATUS}\",
    \"agent_goal_id\": \"${AGENT_GOAL_ID}\"
  }"

Pythonスクリプトからの利用（テキストのみ）

import requests

CAPTAIN_URL = "https://<captain-ai-url>"
PAT = "<your-personal-access-token>"
AGENT_GOAL_ID = "<agent-goal-id>"

response = requests.post(
    f"{CAPTAIN_URL}/api/external/chat",
    headers={"Authorization": f"Bearer {PAT}"},
    json={
        "message": "データ分析を実行してください",
        "agent_goal_id": AGENT_GOAL_ID,
    },
)

print(response.json())  # 202: conversation_id / status: processing

Pythonスクリプトからの利用（ファイル添付）

import requests

CAPTAIN_URL = "https://<captain-ai-url>"
PAT = "<your-personal-access-token>"
AGENT_GOAL_ID = "<agent-goal-id>"

with open("report.txt", "rb") as f:
    response = requests.post(
        f"{CAPTAIN_URL}/api/external/chat",
        headers={"Authorization": f"Bearer {PAT}"},
        data={
            "agent_goal_id": AGENT_GOAL_ID,
            "message": "このレポートを要約してください",
        },
        files=[("files", ("report.txt", f, "text/plain"))],
    )

print(response.json())

セキュリティに関する注意事項

PATは機密情報です。ソースコードにハードコーディングしないでください
環境変数やシークレット管理ツールを使用してPATを管理してください
不要になったPATは速やかに無効化してください
PATが漏洩した可能性がある場合は、直ちに無効化し新しいトークンを生成してください
1ユーザーが同時に保有できる有効なPATは10本までです

概要​

パーソナルアクセストークン（PAT）の取得​

手順​

PATとワークスペース​

エンドポイント一覧​

認証​

レート制限​

チャットAPIの利用​

エンドポイント​

リクエストパラメータ​

リクエスト例（テキストのみ）​

リクエスト例（会話の継続）​

リクエスト例（ファイル添付）​

添付ファイルの制限​

レスポンス​

主なエラー​

業務作成APIの利用​

活用例​

CI/CDパイプラインからの利用​

Pythonスクリプトからの利用（テキストのみ）​

Pythonスクリプトからの利用（ファイル添付）​

セキュリティに関する注意事項​

概要