External API Integration

Overview

Captain.AI lets you access its API externally using a personal access token (PAT). You can run jobs (agents) and create conversations from scripts and external applications.

Note: The chat API is asynchronous. A response is returned as soon as the request is accepted, and AI processing continues in the background. You cannot receive the AI's answer as the API response the way you do on the chat screen.

Getting a Personal Access Token (PAT)

To access the API, you first need to obtain a PAT.

Steps

Log in to Captain.AI
Open Settings > Access Tokens
Click "Create new token" and choose an expiration (30 days / 90 days / 365 days / no expiration)
Copy the generated token (a string starting with cpt_)

Important: The token is shown only at creation time. Be sure to copy it and store it in a safe place.

PATs and Workspaces

A PAT is bound to the workspace it was issued in.

A token can access only the data (jobs, conversations, etc.) of the workspace it was issued in
To use a token in a different workspace, switch to that workspace and issue a new token
You can check which workspace each token is tied to in the list under Settings > Access Tokens

Tip: If you get 404 Not Found for an ID that should be correct, the PAT may have been issued in a different workspace.

Endpoints

Only endpoints under /api/external/ can be used with a PAT (accessing any other API with a PAT returns 403).

Method	Path	Purpose
POST	`/api/external/chat`	Start or continue a conversation with a job (agent)
GET	`/api/external/conversations`	Get a list of your conversations (supports paging)
POST	`/api/external/agent-goals`	Create a job
GET	`/api/external/agent-goals`	Get a list of jobs
GET	`/api/external/agent-goals/{id}`	Get details of a job
GET	`/api/external/workers`	Get a list of available workers
GET	`/api/external/workers/{slug}`	Get details of a worker
GET	`/api/external/me`	Get your own user information

Authentication

Include the PAT in the HTTP header of every request:

Authorization: Bearer cpt_xxxxxxxxxxxxxxxx

Rate Limits

POST /api/external/chat has a rate limit of 60 requests per minute per token. If exceeded, 429 Too Many Requests is returned and the Retry-After header tells you how many seconds to wait before retrying.

Using the Chat API

Endpoint

POST /api/external/chat

Both application/json and multipart/form-data (when attaching files) are supported.

Request Parameters

Parameter	Required	Description
`agent_goal_id`	Yes	ID of the job (agent) to use
`message`	Conditional	Message to send to the AI. Can be omitted if the job has a step with "Allow API execution" enabled (when omitted, only the step's commands are executed)
`conversation_id`	No	ID of an existing conversation. If specified, the message is sent as a continuation of that conversation. If omitted, a new conversation is created
`name`	No	Display name for a new conversation. If omitted, it is named automatically in "job name_date" format
`files`	No	Attached files (only with `multipart/form-data`; multiple files allowed)

Request Example (Text Only)

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月"
  }'

Request Example (Continuing a Conversation)

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>"
  }'

Request Example (File Attachments)

To attach files, send the request in multipart/form-data format.

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"

Note: To attach multiple files, specify the files field multiple times.

Attachment Limits

Up to 100MB per file (up to 300MB for audio/video)
Up to 110MB per request in total (413 if exceeded)
Supported formats: documents (txt / md / csv / json / xlsx / docx / pptx / pdf, etc.), images (png / jpg / gif / webp / svg), audio/video (mp3 / wav / mp4 / webm, etc.), code (js / ts / py / sql, etc.). Unsupported extensions result in an error
Uploaded files are saved in the input/ folder of the worker session

Response

When the request is accepted, 202 Accepted is returned and AI processing continues in the background.

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

The AI's answer is not included in this response
Check the result by opening the conversation in the Captain.AI UI
To track progress via the API, call GET /api/external/conversations periodically and watch for changes in the conversation's message_count and last_message_at

Common Errors

Code	Cause
`401`	Token is invalid, expired, or revoked
`403`	The PAT was used outside `/api/external/`, or you lack access to the job or worker
`404`	The job or conversation does not exist, or you accessed it with a PAT from a different workspace
`422`	Missing parameters (`agent_goal_id` not specified, neither `message` nor an API-enabled step present, etc.)
`429`	Rate limit exceeded (retry after `Retry-After` seconds)
`503`	Worker is unavailable

Using the Job Creation API

You can register jobs (agents) themselves from external systems.

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 }
    ]
  }'

On success, 201 Created is returned with the created job's information
name (job name), steps (array of steps), and category_id (category ID) are required
Steps with use_in_api: true are executed automatically when the chat API is called
Environment variables (env_vars) can be registered but are not included in the response (they are confidential)

Use Cases

From a CI/CD Pipeline

# Report build results to 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}\"
  }"

From a Python Script (Text Only)

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

From a Python Script (File Attachments)

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())

Security Notes

PATs are confidential. Do not hardcode them in source code
Manage PATs with environment variables or a secret management tool
Revoke PATs promptly when they are no longer needed
If a PAT may have been leaked, revoke it immediately and generate a new token
Each user can hold up to 10 active PATs at a time

Overview​

Getting a Personal Access Token (PAT)​

Steps​

PATs and Workspaces​

Endpoints​

Authentication​

Rate Limits​

Using the Chat API​

Endpoint​

Request Parameters​

Request Example (Text Only)​

Request Example (Continuing a Conversation)​

Request Example (File Attachments)​

Attachment Limits​

Response​

Common Errors​

Using the Job Creation API​

Use Cases​

From a CI/CD Pipeline​

From a Python Script (Text Only)​

From a Python Script (File Attachments)​

Security Notes​