Skip to main content
POST
/
api
/
v1
/
tasks
curl -X POST 'https://agent.blackbox.ai/api/v1/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Add a README in French",
    "repoUrl": "https://github.com/org/repo.git",
    "selectedBranch": "main"
  }'

{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assistantMessageId": "msg_abc123xyz456",
  "chatId": "chat_def789ghi012",
  "agentCount": 1
}
This endpoint creates a new agent task. Optionally provide a GitHub repository for the agent to work on.

​
Authentication

All requests require a BLACKBOX API key passed as a Bearer token. To get your API key:
  1. Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
  2. Once provisioning completes, you will be redirected to your Dashboard
  3. From the Dashboard, create an API key to use with all Agent API requests
Your API key will be in the format: sk-xxxxxxxxxxxxxxxxxxxxxx

​
GitHub Connection Required

For GitHub-related tasks: Before creating tasks that work with repositories, you must connect your GitHub account via the API. Call POST /api/v1/git/config with your GitHub personal access token (ghp_…) — the agent uses this token to access and modify your repositories. See Connect GitHub for details.

​
Headers

​
Authorization
string
required
API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560
​
Content-Type
string
required
Must be set to application/json.

​
Request Body

​
message
string
The task description or instruction for the agent. One of message or prompt is required.Examples:
  • "Write a Python script to parse CSV files"
  • "Add unit tests for the authentication module"
  • "Refactor the payment service to use async/await"
​
prompt
string
Alias for message. One of message or prompt is required.
​
type
string
default:"claude"
Routing mode for the request.
  • "claude" — Run a Claude agent task (default). Returns taskId and runId.
  • "standard" — Standard chat completion. Returns an SSE stream with headers x-chat-id and x-message-id.
​
model
string
Model to use for the agent. The id also selects the agent runtime — Anthropic/Claude ids run the Claude Agent SDK; OpenAI/Codex ids (e.g. blackboxai/openai/gpt-5.3-codex) run the Codex SDK. See Models.Example: "blackboxai/anthropic/claude-sonnet-4.6"
​
agent
string
Explicit agent-runtime override — "claude" or "codex". When set, it overrides the runtime that would be inferred from model (e.g. agent: "codex" to run a non-OpenAI model on the Codex runtime). Omit to auto-select from the model id (default: "claude"). See Agent Runtimes for the full selection rule, the shared event stream, and side-by-side examples.
​
systemPromptOverride
string
Custom system prompt for the agent.
​
repoUrl
string
GitHub repository URL for the agent to clone and work on.Example: "https://github.com/org/repo.git"
​
selectedBranch
string
Branch to check out in the repository. Defaults to the repo’s default branch.Example: "main", "develop", "feature/new-api"
​
installDependencies
boolean
default:"false"
Whether to run dependency installation (e.g. npm install) before executing the task.
​
maxDuration
number
default:"300"
Maximum execution time in seconds.Range: 30 – 600. Default: 300.
​
chatId
string
UUID of an existing chat to continue. If omitted, a new chat is created.
​
visibility
string
default:"private"
Visibility of the created chat.
  • "private" — Only you can see it (default)
  • "public" — Publicly accessible

​
Response

​
Claude Agent (type: "claude")

​
taskId
string
Unique identifier for the task (same as runId).
​
runId
string
Unique identifier for this agent run. Use this to poll status, stream logs, or continue the task.
​
assistantMessageId
string
ID of the assistant message being generated in the chat.
​
chatId
string
UUID of the chat thread this task belongs to.
​
agentCount
number
Number of agents spawned. Always 1.

​
Standard Chat (type: "standard")

Returns an SSE stream (text/event-stream) with response headers:
  • x-chat-id — the chat UUID
  • x-message-id — the user message UUID
curl -X POST 'https://agent.blackbox.ai/api/v1/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Add a README in French",
    "repoUrl": "https://github.com/org/repo.git",
    "selectedBranch": "main"
  }'

{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assistantMessageId": "msg_abc123xyz456",
  "chatId": "chat_def789ghi012",
  "agentCount": 1
}

​
Available Models

The default model is blackboxai/anthropic/claude-sonnet-4.6. Pass any of the following in the model field: Claude Agent models (type: "claude" — default):
ModelID
Claude Sonnet 4.6 (default)blackboxai/anthropic/claude-sonnet-4.6
Claude Sonnet 4.5blackboxai/anthropic/claude-sonnet-4.5
Claude Opus 4.6blackboxai/anthropic/claude-opus-4.6
Claude Opus 4.7blackboxai/anthropic/claude-opus-4.7
MiniMax M2.5blackboxai/minimax/minimax-m2.5
Standard chat models (type: "standard"):
ModelID
Mistral Small (default)mistral/mistral-small
MiniMax M2.5minimax/minimax-m2.5
Kimi K2.5moonshotai/kimi-k2.5
Grok 4.1 Fastxai/grok-4.1-fast-non-reasoning
See the Models reference page for the full list with descriptions and usage guidance.

​
Error Codes

Status CodeErrorDescription
200SuccessTask created successfully
400Bad RequestMissing message/prompt, invalid JSON, or validation error
401UnauthorizedInvalid or missing API key
403ForbiddenPro subscription required, or no Blackbox API key configured
404Not FoundGitHub token not found
500Internal Server ErrorFailed to spawn agent or database error