149 lines
3.2 KiB
Markdown
149 lines
3.2 KiB
Markdown
# 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": "..." }`.
|