Blackbox AI Agents API: The Complete Developer Guide

The rise of AI-powered development tools has fundamentally changed how software teams build, debug, and ship code. But what if you could harness multiple AI coding agents programmatically, orchestrate them to work in parallel, and automatically deploy the results? The Blackbox AI Agents API makes this possible, giving developers unprecedented control over a fleet of specialized coding agents through a single, unified interface.

In this comprehensive guide, we'll explore everything you need to know about the AI agents API—from basic single-agent tasks to advanced multi-agent execution patterns that can dramatically accelerate your development workflow. Whether you're building internal tooling, automating code reviews, or creating AI-powered development pipelines, this coding agents API provides the foundation you need.

What You Can Build with the Agents API

Before diving into the technical details, let's explore the possibilities. The Blackbox multi-agent API enables you to build:

• Automated Code Review Systems: Submit pull requests to multiple AI agents for parallel review, then synthesize their feedback into actionable insights.

• Intelligent Refactoring Pipelines: Let different agents tackle various aspects of code modernization—one handles type safety, another optimizes performance, a third improves readability.

• Multi-Perspective Bug Hunting: When debugging complex issues, multiple agents can investigate simultaneously, each bringing unique analytical approaches.

• Automated Feature Implementation: Describe a feature in natural language and let agents implement it directly in your GitHub repository, complete with automatic PR creation.

• CI/CD Intelligence Layers: Integrate AI agents into your deployment pipeline for automated testing, documentation generation, and code quality checks.

The Blackbox API serves as your gateway to these capabilities, providing a consistent interface regardless of which underlying model powers the agent.

API Overview

Base URL

All API requests are made to:

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header of every request:

API keys are prefixed with bb_ and can be generated from your Blackbox dashboard. Keep your API key secure—treat it like a password and never commit it to version control.

Available Agents

The Blackbox AI Agents API provides access to four powerful coding agents, each with distinct strengths and specializations:

Blackbox Agent

• Model ID: blackboxai/blackbox-pro

• Strengths: Full-stack development, rapid prototyping, broad language support

• Best For: General-purpose coding tasks, quick implementations, multi-language projects

Claude Agent

• Model ID: blackboxai/anthropic/claude-sonnet-4.5

• Strengths: Complex reasoning, detailed explanations, careful code analysis

• Best For: Code reviews, architectural decisions, documentation, nuanced refactoring

Codex Agent

• Model ID: gpt-5.2-codex

• Strengths: Code completion, algorithm implementation, mathematical computations

• Best For: Algorithm-heavy tasks, data structures, competitive programming solutions

Gemini Agent

• Model ID: gemini-2.5-pro

• Strengths: Multi-modal understanding, large context handling, cross-file analysis

• Best For: Large codebase analysis, understanding complex dependencies, visual code documentation

Single Agent Tasks

The simplest way to use the API is by dispatching a task to a single agent. This is perfect for straightforward coding requests where you want a specific agent's perspective.

Endpoint

Request Parameters

cURL Example

curl -X POST https://cloud.blackbox.ai/api/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bb_YOUR_API_KEY" \
  -d '{
    "prompt": "Create a REST API endpoint for user authentication with JWT tokens. Include input validation, password hashing with bcrypt, and proper error handling.",
    "agent": "blackbox",
    "model": "blackboxai/blackbox-pro",
    "repoUrl": "https://github.com/yourusername/your-project",
    "branch": "main",
    "maxDuration": 30,
    "installDependencies": true
  }'

Python Example

import requests
import os

class BlackboxAgentClient:
    def __init__(self, api_key: str):
        self.base_url = "https://cloud.blackbox.ai/api"
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}"
        }
    
    def create_task(
        self,
        prompt: str,
        agent: str = "blackbox",
        model: str = "blackboxai/blackbox-pro",
        repo_url: str = None,
        branch: str = "main",
        max_duration: int = 30,
        install_dependencies: bool = False
    ) -> dict:
        """Create a single-agent task."""
        payload = {
            "prompt": prompt,
            "agent": agent,
            "model": model,
            "branch": branch,
            "maxDuration": max_duration,
            "installDependencies": install_dependencies
        }
        
        if repo_url:
            payload["repoUrl"] = repo_url
        
        response = requests.post(
            f"{self.base_url}/tasks",
            json=payload,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Usage
client = BlackboxAgentClient(api_key=os.environ["BLACKBOX_API_KEY"])

task = client.create_task(
    prompt="Implement a rate limiter middleware using the token bucket algorithm",
    agent="claude",
    model="blackboxai/anthropic/claude-sonnet-4.5",
    repo_url="https://github.com/yourusername/api-project",
    branch="feature/rate-limiting"
)

print(f"Task created: {task['taskId']}")

Node.js Example

const axios = require('axios');

class BlackboxAgentClient {
  constructor(apiKey) {
    this.baseUrl = 'https://cloud.blackbox.ai/api';
    this.headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    };
  }

  async createTask({
    prompt,
    agent = 'blackbox',
    model = 'blackboxai/blackbox-pro',
    repoUrl = null,
    branch = 'main',
    maxDuration = 30,
    installDependencies = false
  }) {
    const payload = {
      prompt,
      agent,
      model,
      branch,
      maxDuration,
      installDependencies
    };

    if (repoUrl) {
      payload.repoUrl = repoUrl;
    }

    const response = await axios.post(
      `${this.baseUrl}/tasks`,
      payload,
      { headers: this.headers }
    );

    return response.data;
  }
}

// Usage
const client = new BlackboxAgentClient(process.env.BLACKBOX_API_KEY);

async function main() {
  const task = await client.createTask({
    prompt: 'Add comprehensive unit tests for the UserService class',
    agent: 'codex',
    model: 'gpt-5.2-codex',
    repoUrl: 'https://github.com/yourusername/backend-service',
    branch: 'main'
  });

  console.log(`Task created: ${task.taskId}`);
}

main().catch(console.error);

Multi-Agent Execution: The Killer Feature

While single-agent tasks are powerful, the true potential of the Blackbox API lies in its multi-agent execution capabilities. This feature allows you to dispatch the same task to multiple agents simultaneously, then have a Chairman LLM evaluate and synthesize the best solution.

How It Works

1. Parallel Dispatch: Your task is sent to all selected agents simultaneously, eliminating sequential waiting times.

2. Independent Execution: Each agent works on the problem independently, bringing its unique strengths and perspectives.

3. Chairman Evaluation: Once all agents complete their work, a Chairman LLM analyzes each solution, comparing approaches, code quality, and correctness.

4. Best Solution Selection: The Chairman selects the optimal solution or synthesizes the best elements from multiple responses.

Multi-Agent Request Parameters

Python Multi-Agent Example

import requests
import os
from typing import List, Dict

class BlackboxMultiAgentClient:
    def __init__(self, api_key: str):
        self.base_url = "https://cloud.blackbox.ai/api"
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}"
        }
        
        # Predefined agent configurations
        self.agents = {
            "blackbox": {"agent": "blackbox", "model": "blackboxai/blackbox-pro"},
            "claude": {"agent": "claude", "model": "blackboxai/anthropic/claude-sonnet-4.5"},
            "codex": {"agent": "codex", "model": "gpt-5.2-codex"},
            "gemini": {"agent": "gemini", "model": "gemini-2.5-pro"}
        }
    
    def create_multi_agent_task(
        self,
        prompt: str,
        agent_names: List[str],
        repo_url: str = None,
        branch: str = "main",
        use_chairman: bool = True
    ) -> dict:
        """Create a multi-agent task with parallel execution."""
        
        selected_agents = [
            self.agents[name] for name in agent_names 
            if name in self.agents
        ]
        
        payload = {
            "prompt": prompt,
            "selectedAgents": selected_agents,
            "branch": branch,
            "useChairman": use_chairman
        }
        
        if repo_url:
            payload["repoUrl"] = repo_url
        
        response = requests.post(
            f"{self.base_url}/tasks",
            json=payload,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Usage: Get multiple perspectives on a complex refactoring task
client = BlackboxMultiAgentClient(api_key=os.environ["BLACKBOX_API_KEY"])

task = client.create_multi_agent_task(
    prompt="""Refactor the PaymentProcessor class to:
    1. Implement the Strategy pattern for different payment methods
    2. Add proper error handling and retry logic
    3. Ensure PCI compliance best practices
    4. Add comprehensive logging""",
    agent_names=["blackbox", "claude", "codex"],
    repo_url="https://github.com/yourusername/ecommerce-platform",
    branch="refactor/payment-processor"
)

print(f"Multi-agent task created: {task['taskId']}")
print(f"Agents working: {len(task['agents'])} agents in parallel")

Node.js Multi-Agent Example

const axios = require('axios');

class BlackboxMultiAgentClient {
  constructor(apiKey) {
    this.baseUrl = 'https://cloud.blackbox.ai/api';
    this.headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    };
    
    this.agents = {
      blackbox: { agent: 'blackbox', model: 'blackboxai/blackbox-pro' },
      claude: { agent: 'claude', model: 'blackboxai/anthropic/claude-sonnet-4.5' },
      codex: { agent: 'codex', model: 'gpt-5.2-codex' },
      gemini: { agent: 'gemini', model: 'gemini-2.5-pro' }
    };
  }

  async createMultiAgentTask({
    prompt,
    agentNames,
    repoUrl = null,
    branch = 'main',
    useChairman = true
  }) {
    const selectedAgents = agentNames
      .filter(name => this.agents[name])
      .map(name => this.agents[name]);

    const payload = {
      prompt,
      selectedAgents,
      branch,
      useChairman
    };

    if (repoUrl) {
      payload.repoUrl = repoUrl;
    }

    const response = await axios.post(
      `${this.baseUrl}/tasks`,
      payload,
      { headers: this.headers }
    );

    return response.data;
  }
}

// Usage: Security audit with multiple agents
const client = new BlackboxMultiAgentClient(process.env.BLACKBOX_API_KEY);

async function runSecurityAudit() {
  const task = await client.createMultiAgentTask({
    prompt: `Perform a security audit of the authentication module:
      - Check for SQL injection vulnerabilities
      - Verify proper input sanitization
      - Review session management
      - Identify potential XSS vectors
      - Suggest security improvements`,
    agentNames: ['claude', 'gemini', 'blackbox'],
    repoUrl: 'https://github.com/yourusername/web-app',
    branch: 'main'
  });

  console.log(`Security audit initiated: ${task.taskId}`);
}

runSecurityAudit().catch(console.error);

Working with GitHub Repositories

The Blackbox API integrates seamlessly with GitHub, allowing agents to read, modify, and commit code directly to your repositories.

Connecting Repositories

To work with private repositories, you'll need to connect your GitHub account through the Blackbox dashboard. Once connected, agents can access any repository you have permissions for.

Branch Selection

Always specify a target branch for your tasks. For production safety, we recommend:

• Use feature branches for new implementations

• Use dedicated branches for refactoring tasks

• Never point agents directly at main or production branches for write operations

Automatic PR Creation

When an agent completes a task that modifies code, it can automatically create a pull request:

task = client.create_task(
    prompt="Add input validation to all API endpoints",
    agent="blackbox",
    model="blackboxai/blackbox-pro",
    repo_url="https://github.com/yourusername/api-service",
    branch="feature/input-validation",
    create_pr=True,
    pr_title="Add comprehensive input validation",
    pr_description="Automated implementation of input validation across all endpoints"
)

Vercel Auto-Deploy Integration

For teams using Vercel, the Blackbox API offers automatic deployment integration. When enabled, completed tasks that pass validation are automatically deployed to your Vercel preview environment.

task = client.create_task(
    prompt="Update the landing page hero section with new copy and styling",
    agent="blackbox",
    model="blackboxai/blackbox-pro",
    repo_url="https://github.com/yourusername/marketing-site",
    branch="update/hero-section",
    vercel_auto_deploy=True,
    vercel_project_id="prj_xxxxxxxxxxxx"
)

This creates a seamless workflow: code changes are implemented, committed, and deployed to a preview URL—all from a single API call.

Checking Task Status

Tasks run asynchronously, so you'll need to poll for status updates or configure webhooks.

Endpoint

Python Status Polling Example

import time

def wait_for_task_completion(client, task_id: str, timeout: int = 300) -> dict:
    """Poll task status until completion or timeout."""
    start_time = time.time()
    
    while time.time() - start_time < timeout:
        response = requests.get(
            f"{client.base_url}/tasks/{task_id}",
            headers=client.headers
        )
        response.raise_for_status()
        task = response.json()
        
        status = task.get("status")
        
        if status == "completed":
            print(f"Task completed successfully!")
            return task
        elif status == "failed":
            raise Exception(f"Task failed: {task.get('error')}")
        elif status in ["pending", "running"]:
            print(f"Task status: {status}... waiting")
            time.sleep(10)
        else:
            raise Exception(f"Unknown status: {status}")
    
    raise TimeoutError(f"Task did not complete within {timeout} seconds")

# Usage
task = client.create_task(prompt="Implement caching layer", ...)
result = wait_for_task_completion(client, task["taskId"])
print(f"Result: {result['output']}")

Best Practices

Agent Selection by Task Type

Choose your agents strategically based on the task requirements:

Prompt Writing Tips

1. Be Specific: Instead of "improve the code," say "refactor the UserService class to use dependency injection and add unit tests."

2. Provide Context: Mention relevant files, frameworks, and constraints.

3. Define Success Criteria: Specify what a successful implementation looks like.

4. Break Down Complex Tasks: For large features, create multiple focused tasks rather than one monolithic request.

Error Handling

Always implement robust error handling:

from requests.exceptions import HTTPError, Timeout

try:
    task = client.create_task(prompt="...", ...)
except HTTPError as e:
    if e.response.status_code == 429:
        print("Rate limited. Implement exponential backoff.")
    elif e.response.status_code == 401:
        print("Invalid API key. Check your credentials.")
    else:
        print(f"API error: {e.response.text}")
except Timeout:
    print("Request timed out. Retry with longer timeout.")

Rate Limits and Pricing

The Blackbox API implements rate limiting to ensure fair usage:

Pricing is based on compute time and agent usage. Multi-agent tasks are billed per agent. Check the pricing page for current rates.

Get Started Today

The Blackbox AI Agents API opens up a new paradigm in software development—one where AI agents work alongside your team, handling routine tasks while you focus on architecture and innovation.

Ready to supercharge your development workflow? Get your API key today at blackbox.ai and start building with the most powerful coding agents API available.

Whether you're automating code reviews, building intelligent CI/CD pipelines, or creating the next generation of developer tools, the Blackbox multi-agent API provides the foundation you need. Join thousands of developers already leveraging AI agents to ship better code, faster.

Have questions about the API? Join our Discord community or check out the full API documentation at docs.blackbox.ai.