> ## 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.

# Create an Agent Task

> Create and execute tasks using individual AI agents (BLACKBOX or Claude Code or Codex or Gemini)on repositories.

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](https://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

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

## Headers

<ParamField header="Authorization" type="string" required>
  API Key of the form `Bearer <api_key>`.

  Example: `Bearer bb_b41b647ffbfed27f61656049d3eaeef3d903cc503345d9eb80080d98bc0`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`.
</ParamField>

## Request

<ParamField body="prompt" type="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"
</ParamField>

<ParamField body="repoUrl" type="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`
</ParamField>

<ParamField body="selectedBranch" type="string">
  The branch to work on in the repository. Defaults to `main` if not specified.

  Example: `main`, `develop`, `feature/new-api`
</ParamField>

<ParamField body="selectedAgent" type="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`
</ParamField>

<ParamField body="selectedModel" type="string" required>
  The specific AI model to use with the selected agent. Each agent supports different models.

  See the [Agent Models](#agent-models) section below for available options per agent.

  Default: `blackbox-pro`
</ParamField>

## Agent Models

### Claude Agent

<CodeGroup>
  ```json Available Models theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "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" }
    ]
  }
  ```
</CodeGroup>

**Default Model**: `anthropic/claude-sonnet-4.5`

### BLACKBOX Agent

<CodeGroup>
  ```json Available Models theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "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" }
    ]
  }
  ```
</CodeGroup>

**Default Model**: `blackbox-pro`

### Codex Agent

<CodeGroup>
  ```json Available Models theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "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" }
    ]
  }
  ```
</CodeGroup>

**Default Model**: `gpt-5-codex`

### Gemini Agent

<CodeGroup>
  ```json Available Models theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "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" }
    ]
  }
  ```
</CodeGroup>

**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

<RequestExample>
  ```bash Repository Task theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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"
  }'
  ```

  ```javascript Node.js - Repository Task theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const API_KEY = "YOUR_API_KEY";
  const API_URL = "https://cloud.blackbox.ai/api/tasks";

  const data = {
      prompt: "Create README in French",
      repoUrl: "https://github.com/<org-name>/<repo-name>.git",
      selectedBranch: "main",
      selectedAgent: "blackbox",
      selectedModel: "blackbox-pro"
  };

  const response = await fetch(API_URL, {
      method: "POST",
      headers: {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
      },
      body: JSON.stringify(data),
  });

  const responseData = await response.json();
  console.log(responseData);
  ```

  ```python Python - Repository Task theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  API_KEY = "YOUR_API_KEY"
  API_URL = "https://cloud.blackbox.ai/api/tasks"

  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Bearer {API_KEY}"
  }

  data = {
      "prompt": "Create README in French",
      "repoUrl": "https://github.com/<org-name>/<repo-name>.git",
      "selectedBranch": "main",
      "selectedAgent": "blackbox",
      "selectedModel": "blackbox-pro"
  }

  response = requests.post(API_URL, headers=headers, json=data)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "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"
  }
  ```

  ```json Error Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Invalid agent selected",
    "message": "Agent 'invalid-agent' is not supported. Available agents: claude, blackbox, blackbox-grok, codex, gemini",
    "status": 400
  }
  ```
</ResponseExample>

## 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.