Base URL
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 promptList Tasks
GET /api/v1/tasks — Retrieve your task history with filtersGet Task
GET /api/v1/tasks/:id — Full task details including messagesTask Status
GET /api/v1/tasks/:id/status — Lightweight status pollContinue Task
POST /api/v1/tasks/:id/continue — Send a follow-up promptCancel Task
PATCH /api/v1/tasks/:id — Cancel a running taskTask Logs
GET /api/v1/tasks/:id/logs — Fetch parsed execution eventsStream Logs
GET /api/v1/tasks/:id/logs/stream — Live SSE log streamAgent Status
GET /api/v1/agent/status — Check a run’s status by runIdAgent Stream
GET /api/v1/agent/stream — SSE stream for a specific runIdFile Management
GET /api/v1/tasks/:id/files — List, read, write, delete sandbox filesGitHub Status
GET /api/v1/git/status — Check GitHub connection statusGet GitHub Config
GET /api/v1/git/config — Get connected GitHub account infoStore GitHub Token
POST /api/v1/git/config — Validate and store a GitHub PATList Repositories
GET /api/v1/git/repos — List accessible GitHub repositoriesList Branches
GET /api/v1/git/branches — List branches for a repositoryTask 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 |