Create an Agent Task - BLACKBOX AI

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

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

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:

Click on your Profile Image in the top right corner at cloud.blackbox.ai
Click on “BLACKBOX API Token” from the dropdown menu
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:

Clone the specified repository
Checkout the selected branch
Analyze the codebase
Execute the task within the repository context
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 Code	Error	Description
200	Success	Task created successfully
400	Bad Request	Invalid request (missing prompt, invalid agent/model, invalid repo URL)
401	Unauthorized	Invalid or missing API key
402	Payment Required	Insufficient credits to create task
403	Forbidden	User is not a member of the selected team
404	Not Found	GitHub token not found or user not found
500	Internal Server Error	Task creation failed or database error
502	Bad Gateway	GitHub 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.

Create a Multi-Agent Task Continue an Agent Task

Documentation Index

​Authentication

​GitHub Connection Required

​Headers

​Request

​Agent Models

​Claude Agent

​BLACKBOX Agent

​Codex Agent

​Gemini Agent

​Usage Modes

​Repository Mode

​Error Codes

Authentication

GitHub Connection Required

Headers

Request

Agent Models

Claude Agent

BLACKBOX Agent

Codex Agent

Gemini Agent

Usage Modes

Repository Mode

Error Codes