Create Task

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

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

POST

api

tasks

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

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

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

string

required

API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560

string

required

Must be set to application/json.

Request Body

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"

string

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

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.

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.Example: "blackboxai/anthropic/claude-sonnet-4.6"

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

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.

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.

string

Custom system prompt for the agent.

string

GitHub repository URL for the agent to clone and work on.Example: "https://github.com/org/repo.git"

string

Branch to check out in the repository. Defaults to the repo’s default branch.Example: "main", "develop", "feature/new-api"

boolean

default:"false"

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

number

default:"300"

Maximum execution time in seconds.Range: 30 – 600. Default: 300.

string

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

string

default:"private"

Visibility of the created chat.

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

Response

Claude Agent (`type: "claude"`)

string

Unique identifier for the task (same as runId).

string

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

string

ID of the assistant message being generated in the chat.

string

UUID of the chat thread this task belongs to.

number

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

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

{
  "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

Getting Started

API Reference

Authentication

GitHub Connection Required

Headers

Request Body

Response

Claude Agent (`type: "claude"`)

Standard Chat (`type: "standard"`)

Available Models

Error Codes

​Authentication

​GitHub Connection Required

​Headers

​Request Body

​Response

​Claude Agent (type: "claude")

​Standard Chat (type: "standard")

​Available Models

​Error Codes

Authentication

GitHub Connection Required

Headers

Request Body

Response

Claude Agent (`type: "claude"`)

Standard Chat (`type: "standard"`)

Available Models

Error Codes