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

> Create and execute a task using an AI agent. Supports both standard chat and Claude agent modes.

This endpoint creates a new agent task. Optionally provide a GitHub repository for the agent to work on.

## Authentication

All requests require a BLACKBOX API key passed as a Bearer token. To get your API key:

1. Go to [app.blackbox.ai/agent-api](https://app.blackbox.ai/agent-api) and click **Get an API Key** (requires a Pro subscription)
2. Once provisioning completes, you will be redirected to your [Dashboard](https://app.blackbox.ai/dashboard)
3. From the Dashboard, create an API key to use with all Agent API requests

Your API key will be in the format: `sk-xxxxxxxxxxxxxxxxxxxxxx`

## GitHub Connection Required

<Note>
  **For GitHub-related tasks**: Before creating tasks that work with repositories, you must connect your GitHub account via the API. Call `POST /api/v1/git/config` with your GitHub personal access token (ghp\_...) — the agent uses this token to access and modify your repositories. See [Connect GitHub](/api-reference/v1/git-config-set) for details.
</Note>

## Headers

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

  Example: `Bearer sk_b41b647ffbfed27f616560`
</ParamField>

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

## Request Body

<ParamField body="message" type="string">
  The task description or instruction for the agent. One of `message` or `prompt` is required.

  Examples:

  * `"Write a Python script to parse CSV files"`
  * `"Add unit tests for the authentication module"`
  * `"Refactor the payment service to use async/await"`
</ParamField>

<ParamField body="prompt" type="string">
  Alias for `message`. One of `message` or `prompt` is required.
</ParamField>

<ParamField body="type" type="string" default="claude">
  Routing mode for the request.

  * `"claude"` — Run a Claude agent task (default). Returns `taskId` and `runId`.
  * `"standard"` — Standard chat completion. Returns an SSE stream with headers `x-chat-id` and `x-message-id`.
</ParamField>

<ParamField body="model" type="string">
  Model to use for the agent. The id also selects the **agent runtime** — Anthropic/Claude ids run the **Claude Agent SDK**; OpenAI/Codex ids (e.g. `blackboxai/openai/gpt-5.3-codex`) run the **Codex SDK**. See [Models](/api-reference/v1/models#agent-runtimes-claude-vs-codex).

  Example: `"blackboxai/anthropic/claude-sonnet-4.6"`
</ParamField>

<ParamField body="agent" type="string">
  Explicit agent-runtime override — `"claude"`, `"codex"`, or `"grok"`. When set, it overrides the runtime that would be inferred from `model` (e.g. `agent: "codex"` to run a non-OpenAI model on the Codex runtime). Omit to auto-select from the model id (default: `"claude"`). See [Agent Runtimes](/api-reference/v1/agent-runtimes) for the full selection rule, the shared event stream, and side-by-side examples.
</ParamField>

<ParamField body="apiKey" type="string">
  **Bring-your-own router** — your OpenAI-compatible router key (bearer token). Must be paired with `baseUrl`. When supplied, the sandbox agent is pointed at **your** endpoint instead of the platform router, and `model` is passed through **verbatim** (no allowlist check). The key is used in-memory only and is **never persisted**. The same fields work on [Run Benchmarks](/api-reference/v1/benchmarks#bring-your-own-router).
</ParamField>

<ParamField body="baseUrl" type="string">
  **Bring-your-own router** — your router base URL (e.g. `https://my-router.example.com`). Must be an `http(s)` URL and paired with `apiKey`.
</ParamField>

<ParamField body="systemPromptOverride" type="string">
  Custom system prompt for the agent.
</ParamField>

<ParamField body="repoUrl" type="string">
  GitHub repository URL for the agent to clone and work on.

  Example: `"https://github.com/org/repo.git"`
</ParamField>

<ParamField body="selectedBranch" type="string">
  Branch to check out in the repository. Defaults to the repo's default branch.

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

<ParamField body="installDependencies" type="boolean" default="false">
  Whether to run dependency installation (e.g. `npm install`) before executing the task.
</ParamField>

<ParamField body="maxDuration" type="number" default="300">
  Maximum execution time in seconds.

  Range: `30` – `600`. Default: `300`.
</ParamField>

<ParamField body="chatId" type="string">
  UUID of an existing chat to continue. If omitted, a new chat is created.
</ParamField>

<ParamField body="visibility" type="string" default="private">
  Visibility of the created chat.

  * `"private"` — Only you can see it (default)
  * `"public"` — Publicly accessible
</ParamField>

## Response

### Claude Agent (`type: "claude"`)

<ResponseField name="taskId" type="string">
  Unique identifier for the task (same as `runId`).
</ResponseField>

<ResponseField name="runId" type="string">
  Unique identifier for this agent run. Use this to poll status, stream logs, or continue the task.
</ResponseField>

<ResponseField name="assistantMessageId" type="string">
  ID of the assistant message being generated in the chat.
</ResponseField>

<ResponseField name="chatId" type="string">
  UUID of the chat thread this task belongs to.
</ResponseField>

<ResponseField name="agentCount" type="number">
  Number of agents spawned. Always `1`.
</ResponseField>

### Standard Chat (`type: "standard"`)

Returns an SSE stream (`text/event-stream`) with response headers:

* `x-chat-id` — the chat UUID
* `x-message-id` — the user message UUID

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST 'https://agent.blackbox.ai/api/v1/tasks' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "prompt": "Add a README in French",
      "repoUrl": "https://github.com/org/repo.git",
      "selectedBranch": "main"
    }'
  ```

  ```bash cURL (Codex runtime) theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST 'https://agent.blackbox.ai/api/v1/tasks' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "prompt": "Add a README in French",
      "model": "blackboxai/openai/gpt-5.3-codex",
      "repoUrl": "https://github.com/org/repo.git",
      "selectedBranch": "main"
    }'
  ```

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

  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Add a README in French",
      repoUrl: "https://github.com/org/repo.git",
      selectedBranch: "main",
    }),
  });

  const data = await response.json();
  console.log(data.runId);   // use this to poll status
  console.log(data.chatId);
  ```

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

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

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

  data = {
      "prompt": "Add a README in French",
      "repoUrl": "https://github.com/org/repo.git",
      "selectedBranch": "main",
  }

  response = requests.post(API_URL, headers=headers, json=data)
  result = response.json()
  print(result["runId"])   # use this to poll status
  ```

  ```go Go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      apiKey := "YOUR_API_KEY"
      url := "https://agent.blackbox.ai/api/v1/tasks"

      body, _ := json.Marshal(map[string]interface{}{
          "prompt":         "Add a README in French",
          "repoUrl":        "https://github.com/org/repo.git",
          "selectedBranch": "main",
      })

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer "+apiKey)
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      respBody, _ := io.ReadAll(resp.Body)
      fmt.Println(string(respBody))
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "assistantMessageId": "msg_abc123xyz456",
    "chatId": "chat_def789ghi012",
    "agentCount": 1
  }
  ```

  ```json Error Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "message or prompt is required and must be a non-empty string"
  }
  ```
</ResponseExample>

## Available Models

The default model is `blackboxai/anthropic/claude-sonnet-4.6`. Pass any of the following in the `model` field:

**Claude Agent models** (`type: "claude"` — default):

| Model                         | ID                                       |
| ----------------------------- | ---------------------------------------- |
| Claude Sonnet 4.6 *(default)* | `blackboxai/anthropic/claude-sonnet-4.6` |
| Claude Sonnet 4.5             | `blackboxai/anthropic/claude-sonnet-4.5` |
| Claude Opus 4.6               | `blackboxai/anthropic/claude-opus-4.6`   |
| Claude Opus 4.7               | `blackboxai/anthropic/claude-opus-4.7`   |
| MiniMax M2.5                  | `blackboxai/minimax/minimax-m2.5`        |

**Standard chat models** (`type: "standard"`):

| Model                     | ID                                |
| ------------------------- | --------------------------------- |
| Mistral Small *(default)* | `mistral/mistral-small`           |
| MiniMax M2.5              | `minimax/minimax-m2.5`            |
| Kimi K2.5                 | `moonshotai/kimi-k2.5`            |
| Grok 4.1 Fast             | `xai/grok-4.1-fast-non-reasoning` |

<Tip>
  See the [Models reference](/api-reference/v1/models) page for the full list with descriptions and usage guidance.
</Tip>

## Error Codes

| Status Code | Error                 | Description                                                   |
| ----------- | --------------------- | ------------------------------------------------------------- |
| 200         | Success               | Task created successfully                                     |
| 400         | Bad Request           | Missing `message`/`prompt`, invalid JSON, or validation error |
| 401         | Unauthorized          | Invalid or missing API key                                    |
| 403         | Forbidden             | Pro subscription required, or no Blackbox API key configured  |
| 404         | Not Found             | GitHub token not found                                        |
| 500         | Internal Server Error | Failed to spawn agent or database error                       |