---
title: "HTTP API"
description: "An overview of the local server's programmable surface and its auth model."
---

Bi ships with a local HTTP server (port `8080` by default). Both the web UI and external scripts talk to it. This page maps the programmable surface so you can script or integrate.

> Security note: the server listens on `:8080` (all interfaces) by default. See "Security boundary" at the bottom.

## Auth

Most endpoints require login via a JWT:

```
Authorization: Bearer <token>
```

WebSocket can't carry a header, so it uses `?token=` instead.

- `POST /api/auth/register` — register
- `POST /api/auth/login` — log in, returns a JWT
- `POST /api/auth/logout` — log out
- `GET /api/auth/me` — current user

## Sessions and chat

| Endpoint | Method | Description |
| --- | --- | --- |
| `/api/user/sessions` | `GET` / `POST` | List / create sessions |
| `/api/user/sessions/{id}` | `GET` / `PUT` / `DELETE` | Fetch / update / delete |
| `/api/user/sessions/{id}/messages` | `POST` | Append messages incrementally |
| `/api/user/sessions/{id}/export` | `POST` | Export to Markdown |
| `/api/chat` | `POST` | Run the agent for one turn |
| `/api/remote.mux` | WebSocket | Streaming message channel |
| `/api/terminal` | WebSocket | Terminal panel |

## Config and models

| Endpoint | Method | Description |
| --- | --- | --- |
| `/api/config` | `GET` / `POST` | Read / write runtime config |
| `/api/models` | `GET` / `PUT` | Read / write multi-model config (`.bi/llm.json`) |
| `/api/models/probe` | `POST` | Probe a model endpoint |
| `/api/agent/config` | `GET` / `POST` | Agent runtime parameters |

## Permissions and rules

| Endpoint | Method | Description |
| --- | --- | --- |
| `/api/rules` | `GET` / `POST` | Intercept rule read / write |
| `/api/permission` | `POST` | Approve a permission request |
| `/api/permission/cancel` | `POST` | Cancel a permission request |
| `/api/auto-approve-rules` | `GET` / `POST` | Auto-approval rules |

## Workspace and files

| Endpoint | Method | Description |
| --- | --- | --- |
| `/api/workspace/tree` | `GET` | Directory tree |
| `/api/workspace/file` | `GET` | Read file (text) |
| `/api/workspace/raw` | `GET` | Read file (raw bytes) |
| `/api/workspace/write` | `POST` | Write file |
| `/api/workspace/move` | `POST` | Move / rename |
| `/api/workspace/mkdir` | `POST` | Make directory |
| `/api/workspace/exec` | `POST` | Run a command |
| `/api/workspace/changes` | `GET` | Workspace changes |
| `/api/workspace/restore` | `POST` | Restore a file |
| `/api/workspace/roots` | `GET` | Available project roots |
| `/api/workspace/validate` | `POST` | Validate a directory as a workspace |
| `/api/upload` | `POST` | Upload a file |
| `/uploads/` | `GET` | Access uploaded files |

## Checkpoints and artifacts

| Endpoint | Method | Description |
| --- | --- | --- |
| `/api/checkpoint` | `GET` / `POST` | List / create checkpoints |
| `/api/checkpoint/{id}` | `GET` / `POST` | Checkpoint detail / rollback |

## Misc

| Endpoint | Method | Description |
| --- | --- | --- |
| `/api/stats` | `GET` | Usage stats |
| `/api/system/info` | `GET` | System info (including the telemetry flag) |
| `/api/skills` | `GET` | Skill list |
| `/api/conversation/network` | `GET` | Network activity log |

## Security boundary

**By default the server listens on all interfaces (`0.0.0.0:8080`), and a few endpoints have no login check.** Confirm for yourself who can reach this port:

- Other devices on the LAN, other local processes, and port forwards can all touch it
- Decide for your scenario whether to narrow exposure via a firewall, a reverse proxy, or a different bind address
- Do not treat it as an authentication layer — it is a local development tool first