Create a Multi-Agent Task

Multi-Agent Tasks allow you to run the same task across multiple AI agents in parallel, enabling you to compare different approaches, validate implementations, and choose the best solution for your needs.

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 Parameters

prompt

string

required

The task description or instruction for the AI agents to execute. All agents will work on the same prompt.Examples:

“Add Stripe Payment Gateway”
“Implement user authentication with JWT”
“Refactor the payment processing module”
“Add comprehensive unit tests”

selectedAgents

array

required

An array of agent configurations. Each agent will independently execute the task in parallel.Structure: Each object must contain:

agent (string, required): The agent type
model (string, required): The specific model to use

Available Agents:

claude - Anthropic’s Claude models
blackbox - BLACKBOX AI models
codex - OpenAI’s GPT models
gemini - Google’s Gemini models

Example:

[
  {
    "agent": "claude",
    "model": "blackboxai/anthropic/claude-sonnet-4.5"
  },
  {
    "agent": "blackbox",
    "model": "blackboxai/blackbox-pro"
  },
  {
    "agent": "gemini",
    "model": "gemini-2.0-flash-exp"
  }
]

Minimum: 2 agents
Maximum: 5 agents

repoUrl

string

GitHub repository URL to work on. If provided, all agents will work on this repository.Example: https://github.com/username/repository.git

selectedBranch

string

The branch to work on in the repository. Defaults to main if not specified.Example: main, master, develop, feature/new-feature

Available Agent Models

Claude Agent

{
  "agent": "claude",
  "model": "blackboxai/anthropic/claude-sonnet-4.5" // or claude-sonnet-4, claude-opus-4.5
}

Available Models:

blackboxai/anthropic/claude-sonnet-4.5 - Latest Sonnet (Recommended)
blackboxai/anthropic/claude-sonnet-4 - Sonnet 4
blackboxai/anthropic/claude-opus-4.5 - Most capable Claude model

BLACKBOX Agent

{
  "agent": "blackbox",
  "model": "blackboxai/blackbox-pro" // or other blackbox models
}

Available Models:

blackboxai/blackbox-pro - BLACKBOX PRO (Recommended)
blackboxai/anthropic/claude-sonnet-4.5 - Claude via BLACKBOX
blackboxai/openai/gpt-5.2-codex - GPT-5.2 Codex via BLACKBOX
blackboxai/anthropic/claude-opus-4.5 - Claude Opus via BLACKBOX
blackboxai/x-ai/grok-code-fast-1:free - Grok Code (Free)
blackboxai/google/gemini-2.5-pro - Gemini via BLACKBOX

Codex Agent

{
  "agent": "codex",
  "model": "gpt-5-codex" // or other OpenAI models
}

Available Models:

gpt-5.2-codex - GPT-5.2 Codex (Recommended)
openai/gpt-5 - GPT-5
openai/gpt-5-mini - GPT-5 Mini
openai/gpt-5-nano - GPT-5 Nano
openai/gpt-4.1 - GPT-4.1

Gemini Agent

{
  "agent": "gemini",
  "model": "gemini-2.0-flash-exp" // or other Gemini models
}

Available Models:

gemini-2.0-flash-exp - Gemini 2.0 Flash (Recommended)
gemini-2.5-pro - Gemini 2.5 Pro
gemini-2.5-flash - Gemini 2.5 Flash

How Multi-Agent Tasks Work

Task Submission: You submit a single task with multiple agent configurations
Parallel Execution: Each agent independently processes the task simultaneously
Independent Analysis: Each agent analyzes the codebase and creates its own solution
Separate Commits: Each agent creates its own commits (if working on a repository)
Result Aggregation: All results are tracked in the agentExecutions array
Comparison: You can compare approaches, code quality, and results across all agents

Response Structure

The response includes several fields specific to multi-agent tasks:

selectedAgents: Array of agent configurations used (always present when multi-agent task is created)
multiLaunch: Initially false, becomes true when agents start executing
agentExecutions: Initially null, populated when agents start executing. Once populated, contains:
- agent: The agent type
- model: The model used
- status: Current status (pending, in_progress, completed, failed)
- executionId: Unique identifier for this agent’s execution
- result: The agent’s output (when completed)
- commits: Array of commits made by this agent
- error: Error message (if failed)

Note: When you first create a multi-agent task, agentExecutions will be null and multiLaunch will be false. You need to poll the task status to see when agents start executing and agentExecutions gets populated.

curl --location 'https://cloud.blackbox.ai/api/tasks' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "Add README in Mandarin",
    "repoUrl": "https://github.com/<org_name>/<repo_name>.git",
    "selectedBranch": "main",
    "selectedAgents": [
        {
            "agent": "claude",
            "model": "blackboxai/anthropic/claude-sonnet-4.5"
        },
        {
            "agent": "blackbox",
            "model": "blackboxai/blackbox-pro"
        }
    ]
}'

{
  "task": {
    "id": "4GsNQMMsGZpv8x_J9ms6L",
    "userId": "user@gmail.com",
    "teamId": null,
    "prompt": "add readme in mandarin",
    "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": [
      {
        "agent": "claude",
        "model": "blackboxai/anthropic/claude-sonnet-4.5"
      },
      {
        "agent": "blackbox",
        "model": "blackboxai/blackbox-pro"
      }
    ],
    "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-20T20:16:19.489Z",
    "updatedAt": "2025-11-20T20:16:19.489Z",
    "completedAt": null,
    "slackUserId": null,
    "slackTeamId": null,
    "slackChannelId": null,
    "slackMessageTs": null,
    "badge": null,
    "batchId": null,
    "isPublic": false,
    "isEmptyGitUser": false,
    "metaData": null
  },
  "taskUrl": "https://cloud.blackbox.ai/tasks/4GsNQMMsGZpv8x_J9ms6L"
}

Best Practices

Agent Selection

Diverse Models: Choose agents with different strengths

{
  "selectedAgents": [
    { "agent": "claude", "model": "blackboxai/anthropic/claude-sonnet-4.5" },  // Great for complex reasoning
    { "agent": "codex", "model": "gpt-5-codex" },                              // Excellent for code generation
    { "agent": "gemini", "model": "gemini-2.0-flash-exp" }                     // Fast and efficient
  ]
}

Similar Models: Compare variations of the same model family

{
  "selectedAgents": [
    { "agent": "claude", "model": "blackboxai/anthropic/claude-sonnet-4.5" },
    { "agent": "claude", "model": "blackboxai/anthropic/claude-opus-4.5" }
  ]
}

Use Cases

Complex Refactoring: Get multiple approaches to restructuring code

{
  "prompt": "Refactor the authentication module to use dependency injection",
  "selectedAgents": [/* 3-4 different agents */]
}

Critical Features: Validate implementation across multiple agents

{
  "prompt": "Implement payment processing with Stripe integration",
  "selectedAgents": [/* 2-3 agents for validation */]
}

Documentation: Compare documentation styles and completeness

{
  "prompt": "Add comprehensive API documentation",
  "selectedAgents": [/* 2-3 agents */]
}

Performance Tips

Optimal Agent Count: Use 2-3 agents for most tasks, up to 5 for critical comparisons
Task Complexity: More complex tasks benefit more from multi-agent approach
Resource Awareness: Multi-agent tasks consume more credits and take longer
Result Analysis: Focus on comparing approach and quality, not just output
Polling Frequency: Check status every 5-10 seconds to avoid rate limits

Comparison Metrics

When comparing agent results, consider:

Code Quality: Readability, maintainability, best practices
Completeness: Does it fully address the prompt?
Efficiency: Performance and resource usage
Error Handling: Robustness and edge case coverage
Documentation: Code comments and explanations
Testing: Test coverage and quality
Consistency: Adherence to project conventions

Limitations

Minimum Agents: At least 2 agents required
Maximum Agents: Up to 5 agents recommended
Execution Time: Longer than single-agent tasks
Credit Usage: Consumes credits for each agent execution
Conflicts: Agents may create conflicting changes (manual merge may be needed)

Create Single Agent Task - Standard single-agent task execution

Error Codes

Status Code	Error	Description
200	Success	Multi-agent task created successfully
400	Bad Request	Invalid request (missing prompt, invalid agents, less than 2 agents)
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

Endpoints

Documentation Index

​Authentication

​GitHub Connection Required

​Headers

​Request Parameters

​Available Agent Models

​Claude Agent

​BLACKBOX Agent

​Codex Agent

​Gemini Agent

​How Multi-Agent Tasks Work

​Response Structure

​Best Practices

​Agent Selection

​Use Cases

​Performance Tips

​Comparison Metrics

​Limitations

​Related Endpoints

​Error Codes

Authentication

GitHub Connection Required

Headers

Request Parameters

Available Agent Models

Claude Agent

BLACKBOX Agent

Codex Agent

Gemini Agent

How Multi-Agent Tasks Work

Response Structure

Best Practices

Agent Selection

Use Cases

Performance Tips

Comparison Metrics

Limitations

Related Endpoints

Error Codes