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