Introduction

Programmatically create, monitor, and manage AI agent tasks using the BLACKBOX Agent API.

The BLACKBOX Agent API gives you full programmatic control over AI agent tasks — from creating and monitoring runs to streaming live logs, managing sandbox files, and continuing conversations.

Base URL

https://agent.blackbox.ai/api/v1

Authentication

All endpoints require a BLACKBOX API key passed as a Bearer token. See the Authentication page for full details on getting your API key and using it in requests.

Endpoints Overview

Create Task

POST /api/v1/tasks — Launch an agent task with a prompt

List Tasks

GET /api/v1/tasks — Retrieve your task history with filters

Get Task

GET /api/v1/tasks/:id — Full task details including messages

Task Status

GET /api/v1/tasks/:id/status — Lightweight status poll

Continue Task

POST /api/v1/tasks/:id/continue — Send a follow-up prompt

Cancel Task

PATCH /api/v1/tasks/:id — Cancel a running task

Task Logs

GET /api/v1/tasks/:id/logs — Fetch parsed execution events

Stream Logs

GET /api/v1/tasks/:id/logs/stream — Live SSE log stream

Agent Status

GET /api/v1/agent/status — Check a run’s status by runId

Agent Stream

GET /api/v1/agent/stream — SSE stream for a specific runId

File Management

GET /api/v1/tasks/:id/files — List, read, write, delete sandbox files

GitHub Status

GET /api/v1/git/status — Check GitHub connection status

Get GitHub Config

GET /api/v1/git/config — Get connected GitHub account info

Store GitHub Token

POST /api/v1/git/config — Validate and store a GitHub PAT

List Repositories

GET /api/v1/git/repos — List accessible GitHub repositories

List Branches

GET /api/v1/git/branches — List branches for a repository

Task Status Values

Status	Description
queued	Task is waiting to start
running	Agent is actively executing
completed	Task finished successfully
failed	Task encountered an error
cancelled	Task was cancelled by user
interrupted	Task was interrupted (e.g. server restart)

Error Codes

Status Code	Description
400	Bad Request — invalid parameters or body
401	Unauthorized — missing or invalid API key
403	Forbidden — insufficient plan or access denied
404	Not Found — task or resource does not exist
500	Internal Server Error