> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/v1/authentication) page for full details on getting your API key and using it in requests.

## Endpoints Overview

<CardGroup cols={2}>
  <Card title="Create Task" href="/api-reference/v1/create-task/">
    `POST /api/v1/tasks` — Launch an agent task with a prompt
  </Card>

  <Card title="List Tasks" href="/api-reference/v1/list-tasks/">
    `GET /api/v1/tasks` — Retrieve your task history with filters
  </Card>

  <Card title="Get Task" href="/api-reference/v1/get-task/">
    `GET /api/v1/tasks/:id` — Full task details including messages
  </Card>

  <Card title="Task Status" href="/api-reference/v1/task-status/">
    `GET /api/v1/tasks/:id/status` — Lightweight status poll
  </Card>

  <Card title="Continue Task" href="/api-reference/v1/continue-task/">
    `POST /api/v1/tasks/:id/continue` — Send a follow-up prompt
  </Card>

  <Card title="Cancel Task" href="/api-reference/v1/cancel-task/">
    `PATCH /api/v1/tasks/:id` — Cancel a running task
  </Card>

  <Card title="Task Logs" href="/api-reference/v1/task-logs/">
    `GET /api/v1/tasks/:id/logs` — Fetch parsed execution events
  </Card>

  <Card title="Stream Logs" href="/api-reference/v1/stream-logs/">
    `GET /api/v1/tasks/:id/logs/stream` — Live SSE log stream
  </Card>

  <Card title="Agent Status" href="/api-reference/v1/agent-status/">
    `GET /api/v1/agent/status` — Check a run's status by runId
  </Card>

  <Card title="Agent Stream" href="/api-reference/v1/agent-stream/">
    `GET /api/v1/agent/stream` — SSE stream for a specific runId
  </Card>

  <Card title="File Management" href="/api-reference/v1/files-list/">
    `GET /api/v1/tasks/:id/files` — List, read, write, delete sandbox files
  </Card>

  <Card title="GitHub Status" href="/api-reference/v1/git-status/">
    `GET /api/v1/git/status` — Check GitHub connection status
  </Card>

  <Card title="Get GitHub Config" href="/api-reference/v1/git-config-get/">
    `GET /api/v1/git/config` — Get connected GitHub account info
  </Card>

  <Card title="Store GitHub Token" href="/api-reference/v1/git-config-set/">
    `POST /api/v1/git/config` — Validate and store a GitHub PAT
  </Card>

  <Card title="List Repositories" href="/api-reference/v1/git-repos/">
    `GET /api/v1/git/repos` — List accessible GitHub repositories
  </Card>

  <Card title="List Branches" href="/api-reference/v1/git-branches/">
    `GET /api/v1/git/branches` — List branches for a repository
  </Card>
</CardGroup>

## 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                          |