Skip to main content
POST
/
api
/
tasks
curl --location 'https://cloud.blackbox.ai/api/tasks' \
--header 'Authorization: Bearer bb_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "Create README in French",
    "repoUrl": "https://github.com/<org-name>/<repo-name>.git",
    "selectedBranch": "main",
    "selectedAgent": "blackbox",
    "selectedModel": "blackboxai/blackbox-pro"
}'

{
  "task": {
    "id": "ac2wbk3lXAufdSdIscsirg",
    "userId": "email@gmail.com",
    "teamId": null,
    "prompt": "Create README in French",
    "repoUrl": "https://github.com/<org-name>/<repo-name>.git",
    "selectedAgent": "blackbox",
    "selectedModel": "blackboxai/blackbox-pro",
    "installDependencies": false,
    "maxDuration": 300,
    "keepAlive": false,
    "status": "pending",
    "progress": 0,
    "logs": [],
    "followupMessages": null,
    "checkpoint": null,
    "error": null,
    "selectedBranch": "main",
    "branchName": null,
    "sandboxUrl": null,
    "sandboxId": null,
    "agentSandboxConfig": null,
    "merged": false,
    "prNumber": null,
    "prUrl": null,
    "multiLaunch": false,
    "selectedAgents": null,
    "agentExecutions": null,
    "diffAnalysis": null,
    "diffStats": null,
    "cumulativeDiff": null,
    "taskSource": "manual",
    "scheduledTaskId": null,
    "repoInstructions": null,
    "environmentVariables": null,
    "testAccounts": null,
    "autoDeployEnabled": false,
    "deploymentProvider": "vercel",
    "vercelDeploymentSettings": null,
    "gcloudDeploymentSettings": null,
    "deployments": null,
    "lock": null,
    "createdAt": "2025-11-19T23:40:21.585Z",
    "updatedAt": "2025-11-19T23:40:21.585Z",
    "completedAt": null,
    "slackUserId": null,
    "slackTeamId": null,
    "slackChannelId": null,
    "slackMessageTs": null,
    "badge": null,
    "batchId": null,
    "isPublic": false,
    "isEmptyGitUser": true,
    "metaData": null
  }
}
This endpoint allows you to create tasks that AI agents can execute. You can either:
  • Work on a repository: Provide a repoUrl to have the agent analyze and modify code in a GitHub repository
  • Standalone prompt: Omit repoUrl to treat the request as a direct prompt for the agent to perform actions

​
Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:
  1. Click on your Profile Image in the top right corner at cloud.blackbox.ai
  2. Click on “BLACKBOX MCP Token” from the dropdown menu
  3. Copy the existing token or click “Generate” if you don’t have one yet
Your API key will be in the format: bb_xxxxxxxxxxxxxxxxxxxxxx

​
Headers

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

​
Request

​
prompt
string
required
The task description or instruction for the AI agent to execute. Be specific about what you want the agent to do.Examples:
  • “Create README in French”
  • “Add unit tests for authentication module”
  • “Refactor the database connection logic”
  • “Write a Python script to process CSV files”
​
repoUrl
string
GitHub repository URL to work on. If provided, the agent will clone and work on this repository.Important: If repoUrl is not passed, the request will be treated as a standalone prompt for the agent to perform actions without a repository context.Example: https://github.com/<org-name>/<repo-name>.git
​
selectedBranch
string
The branch to work on in the repository. Defaults to main if not specified.Example: main, develop, feature/new-api
​
selectedAgent
string
required
The AI agent to use for executing the task. Each agent has different capabilities and specializations.Available agents:
  • claude - Anthropic’s Claude models (Sonnet 4.5, Sonnet 4, Opus 4)
  • blackbox - BLACKBOX AI models with multiple provider options
  • codex - OpenAI’s GPT models (GPT-5, GPT-4.1)
  • gemini - Google’s Gemini models (2.0 Flash, 2.5 Pro)
Default: blackbox
​
selectedModel
string
required
The specific AI model to use with the selected agent. Each agent supports different models.See the Agent Models section below for available options per agent.Default: blackboxai/blackbox-pro

​
Agent Models

​
Claude Agent

{
  "claude": [
    { "value": "blackboxai/anthropic/claude-sonnet-4.5", "label": "Sonnet 4.5" },
    { "value": "blackboxai/anthropic/claude-sonnet-4", "label": "Sonnet 4" },
    { "value": "blackboxai/anthropic/claude-opus-4", "label": "Opus 4" }
  ]
}
Default Model: blackboxai/anthropic/claude-sonnet-4.5

​
BLACKBOX Agent

{
  "blackbox": [
    { "value": "blackboxai/blackbox-pro", "label": "BLACKBOX PRO" },
    { "value": "blackboxai/anthropic/claude-sonnet-4.5", "label": "Claude Sonnet 4.5" },
    { "value": "blackboxai/openai/gpt-5-codex", "label": "GPT-5 Codex" },
    { "value": "blackboxai/anthropic/claude-opus-4", "label": "Claude Opus 4" },
    { "value": "blackboxai/x-ai/grok-code-fast-1:free", "label": "Grok Code Fast (Free)" },
    { "value": "blackboxai/google/gemini-2.5-pro", "label": "Gemini 2.5 Pro" }
  ]
}
Default Model: blackboxai/blackbox-pro

​
Codex Agent

{
  "codex": [
    { "value": "openai/gpt-5", "label": "GPT-5" },
    { "value": "gpt-5-codex", "label": "GPT-5-Codex" },
    { "value": "openai/gpt-5-mini", "label": "GPT-5 Mini" },
    { "value": "openai/gpt-5-nano", "label": "GPT-5 Nano" },
    { "value": "openai/gpt-4.1", "label": "GPT-4.1" }
  ]
}
Default Model: gpt-5-codex

​
Gemini Agent

{
  "gemini": [
    { "value": "gemini-2.0-flash-exp", "label": "Gemini 2.0 Flash" },
    { "value": "gemini-2.5-pro", "label": "Gemini 2.5 Pro" },
    { "value": "gemini-2.5-flash", "label": "Gemini 2.5 Flash" }
  ]
}
Default Model: gemini-2.0-flash-exp

​
Usage Modes

​
Repository Mode

When repoUrl is provided, the agent will:
  1. Clone the specified repository
  2. Checkout the selected branch
  3. Analyze the codebase
  4. Execute the task within the repository context
  5. Create commits with the changes

​
Standalone Mode

When repoUrl is not provided, the agent will:
  1. Treat the prompt as a standalone instruction
  2. Execute the task without repository context
  3. Return results or generated code directly
This is useful for:
  • Code generation tasks
  • Algorithm implementation
  • Documentation writing
  • Quick scripts or utilities
  • Q&A or explanations
curl --location 'https://cloud.blackbox.ai/api/tasks' \
--header 'Authorization: Bearer bb_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "Create README in French",
    "repoUrl": "https://github.com/<org-name>/<repo-name>.git",
    "selectedBranch": "main",
    "selectedAgent": "blackbox",
    "selectedModel": "blackboxai/blackbox-pro"
}'

{
  "task": {
    "id": "ac2wbk3lXAufdSdIscsirg",
    "userId": "email@gmail.com",
    "teamId": null,
    "prompt": "Create README in French",
    "repoUrl": "https://github.com/<org-name>/<repo-name>.git",
    "selectedAgent": "blackbox",
    "selectedModel": "blackboxai/blackbox-pro",
    "installDependencies": false,
    "maxDuration": 300,
    "keepAlive": false,
    "status": "pending",
    "progress": 0,
    "logs": [],
    "followupMessages": null,
    "checkpoint": null,
    "error": null,
    "selectedBranch": "main",
    "branchName": null,
    "sandboxUrl": null,
    "sandboxId": null,
    "agentSandboxConfig": null,
    "merged": false,
    "prNumber": null,
    "prUrl": null,
    "multiLaunch": false,
    "selectedAgents": null,
    "agentExecutions": null,
    "diffAnalysis": null,
    "diffStats": null,
    "cumulativeDiff": null,
    "taskSource": "manual",
    "scheduledTaskId": null,
    "repoInstructions": null,
    "environmentVariables": null,
    "testAccounts": null,
    "autoDeployEnabled": false,
    "deploymentProvider": "vercel",
    "vercelDeploymentSettings": null,
    "gcloudDeploymentSettings": null,
    "deployments": null,
    "lock": null,
    "createdAt": "2025-11-19T23:40:21.585Z",
    "updatedAt": "2025-11-19T23:40:21.585Z",
    "completedAt": null,
    "slackUserId": null,
    "slackTeamId": null,
    "slackChannelId": null,
    "slackMessageTs": null,
    "badge": null,
    "batchId": null,
    "isPublic": false,
    "isEmptyGitUser": true,
    "metaData": null
  }
}
To use multi-launch mode, create multiple task requests with different agents and the same prompt, then compare the results.