Create Task

POSThttps://agent.blackbox.ai/api/v1/tasks

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:

Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
Once provisioning completes, you will be redirected to your Dashboard
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

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 for details.

Headers

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Content-Typestringrequired

Must be set to application/json.

Request Body

messagestring

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"

promptstring

Alias for message. One of message or prompt is required.

typestringdefault: 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.

modelstring

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.

Example: "blackboxai/anthropic/claude-sonnet-4.6"

agentstring

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 for the full selection rule, the shared event stream, and side-by-side examples.

apiKeystring

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.

baseUrlstring

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.

systemPromptOverridestring

Custom system prompt for the agent.

repoUrlstring

GitHub repository URL for the agent to clone and work on.

Example: "https://github.com/org/repo.git"

selectedBranchstring

Branch to check out in the repository. Defaults to the repo's default branch.

Example: "main", "develop", "feature/new-api"

installDependenciesbooleandefault: false

Whether to run dependency installation (e.g. npm install) before executing the task.

maxDurationnumberdefault: 300

Maximum execution time in seconds.

Range: 30 – 600. Default: 300.

chatIdstring

UUID of an existing chat to continue. If omitted, a new chat is created.

visibilitystringdefault: private

Visibility of the created chat.

"private" — Only you can see it (default)
"public" — Publicly accessible

Response

Claude Agent (`type: "claude"`)

taskIdstring

Unique identifier for the task (same as runId).

runIdstring

Unique identifier for this agent run. Use this to poll status, stream logs, or continue the task.

assistantMessageIdstring

ID of the assistant message being generated in the chat.

chatIdstring

UUID of the chat thread this task belongs to.

agentCountnumber

Number of agents spawned. Always 1.

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

Request Example

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

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

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);

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

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

Response Example

{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assistantMessageId": "msg_abc123xyz456",
  "chatId": "chat_def789ghi012",
  "agentCount": 1
}

{
  "error": "message or prompt is required and must be a non-empty string"
}

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`

See the Models reference page for the full list with descriptions and usage guidance.

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