Skip to main content
POST
/
api
/
tasks
curl --location 'https://cloud.blackbox.ai/api/tasks' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "Add Stripe Payment Integration",
    "repoUrl": "https://github.com/<org-name>/<repo-name>.git",
    "selectedBranch": "main",
    "selectedAgent": "blackbox",
    "selectedModel": "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": "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
  },
  "taskUrl": "https://cloud.blackbox.ai/tasks/ac2wbk3lXAufdSdIscsirg"
}

Documentation Index

Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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 API 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

​
GitHub Connection Required

For GitHub-related tasks: Make sure you have connected your GitHub account on https://cloud.blackbox.ai before creating tasks that work with repositories. This is required for the agent to access and modify your repositories.

​
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.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.5)
  • blackbox - BLACKBOX AI models with multiple provider options
  • codex - OpenAI’s GPT models (GPT-5.2-Codex, 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: blackbox-pro

​
Agent Models

​
Claude Agent

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

​
BLACKBOX Agent

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

​
Codex Agent

{
  "codex": [
    { "value": "gpt-5.2-codex", "label": "GPT-5.2-Codex" },
    { "value": "gpt-5-codex", "label": "GPT-5-Codex" },
    { "value": "gpt-5-mini", "label": "GPT-5 Mini" },
    { "value": "gpt-5-nano", "label": "GPT-5 Nano" },
    { "value": "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
curl --location 'https://cloud.blackbox.ai/api/tasks' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "Add Stripe Payment Integration",
    "repoUrl": "https://github.com/<org-name>/<repo-name>.git",
    "selectedBranch": "main",
    "selectedAgent": "blackbox",
    "selectedModel": "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": "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
  },
  "taskUrl": "https://cloud.blackbox.ai/tasks/ac2wbk3lXAufdSdIscsirg"
}

​
Error Codes

Status CodeErrorDescription
200SuccessTask created successfully
400Bad RequestInvalid request (missing prompt, invalid agent/model, invalid repo URL)
401UnauthorizedInvalid or missing API key
402Payment RequiredInsufficient credits to create task
403ForbiddenUser is not a member of the selected team
404Not FoundGitHub token not found or user not found
500Internal Server ErrorTask creation failed or database error
502Bad GatewayGitHub API error or file upload failed
To use multi-launch mode, create multiple task requests with different agents and the same prompt, then compare the results.