# opencode serve — HTTP API reference

Minimal reference for the endpoints used by `libaihelloworld.lua`. Full spec served at `GET /doc` when the server is running.

## Running the server

```bash
opencode serve \
  --hostname 127.0.0.1 \
  --port 4096
```

With Basic Auth (recommended):

```bash
OPENCODE_SERVER_PASSWORD=secret opencode serve \
  --hostname 127.0.0.1 \
  --port 4096
```

Default username is `opencode`. Override with `OPENCODE_SERVER_USERNAME`.

## Authentication

All requests must include `Authorization: Basic <base64(username:password)>` when the server was started with a password. No auth header is needed if no password is set.

```
Authorization: Basic base64("opencode:secret")
```

## Endpoints

### `GET /global/health`

Health check. Returns `200` when the server is up.

---

### `GET /session`

List all sessions for the current project.

**Response** `200`:
```json
[
  { "id": "ses_abc123", "title": "my session", "time": { "created": 1234567890, "updated": 1234567890 } }
]
```

---

### `POST /session`

Create a new session.

**Request body:**
```json
{ "title": "optional title", "parentID": "optional" }
```

**Response** `200`:
```json
{ "id": "ses_abc123", "title": "my session" }
```

---

### `POST /session/:id/message`

Send a message and wait for the AI reply (blocking). Returns when the assistant has finished responding.

**Request body:**
```json
{
  "parts": [
    { "type": "text", "text": "your prompt here" }
  ],
  "model": { "providerID": "anthropic", "modelID": "claude-opus-4-7" }
}
```

`model` is optional — omit to use the server's configured default.

**Response** `200`:
```json
{
  "info": { "id": "msg_xyz", "sessionID": "ses_abc123", "role": "assistant" },
  "parts": [
    { "type": "text", "text": "the reply" }
  ]
}
```

Parts can include non-text types (`tool-call`, `step-start`, etc.) — collect all `type == "text"` entries to reconstruct the reply.

**Errors:**
- `401` — wrong credentials
- `404` — session not found (may have been deleted or server restarted)
- `504` — AI took too long

---

### `DELETE /session/:id`

Delete a session.

---

### `POST /session/:id/abort`

Abort a running generation.

---

### `POST /session/:id/prompt_async`

Fire-and-forget variant. Returns `204` immediately; result arrives over the SSE stream.

---

### `GET /global/event` (SSE)

Server-Sent Events stream. Delivers all server bus events in real time. Useful for async workflows or watching a session from outside the TUI.

---

## opencode attach

`opencode attach` opens the TUI and connects it to an already-running `opencode serve` instance. Both the TUI and any HTTP clients operate on the same session state.

```bash
opencode attach http://127.0.0.1:4096
opencode attach http://127.0.0.1:4096 --session ses_abc123
```

To send messages to the session currently open in the TUI, set `opencc.session_id` in CC to the session ID shown in the TUI, then run `ai-helloworld`.

## TUI control (bonus)

When a TUI is attached, these endpoints drive it programmatically:

| Method | Path | Effect |
|---|---|---|
| `POST` | `/tui/append-prompt` | Append text to the input field |
| `POST` | `/tui/submit-prompt` | Submit the current input |
| `POST` | `/tui/show-toast` | Show a notification |

Body for append/submit: `{ "text": "..." }`.