204 lines
6.0 KiB
Markdown
204 lines
6.0 KiB
Markdown
# opencode serve — HTTP API reference
|
|
|
|
Minimal reference for the endpoints used by `libai.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
|
|
|
|
---
|
|
|
|
### `GET /session/:id/message/:messageID`
|
|
|
|
Get a message by ID. Opencode validates caller-provided message IDs; use IDs starting with `msg`.
|
|
|
|
**Response** `200`:
|
|
```json
|
|
{
|
|
"info": { "id": "msg_xyz", "sessionID": "ses_abc123", "role": "assistant", "time": { "completed": 1234567890 } },
|
|
"parts": [
|
|
{ "type": "text", "text": "the reply" }
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `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. Include `messageID` in the request body so the submitted message can be matched to the later assistant response. Opencode validates caller-provided message IDs; use IDs starting with `msg`.
|
|
|
|
**Request body:**
|
|
```json
|
|
{
|
|
"messageID": "msg_xyz",
|
|
"parts": [
|
|
{ "type": "text", "text": "your prompt here" }
|
|
],
|
|
"model": { "providerID": "anthropic", "modelID": "claude-opus-4-7" }
|
|
}
|
|
```
|
|
|
|
Unlike `/message`, `model` is **not** optional in practice — omitting it causes the request to be accepted (`204`) without triggering generation, so the assistant message never appears. `ai` only uses this async endpoint when `opencc.provider_id` and `opencc.model_id` are configured; otherwise it falls back to blocking `POST /session/:id/message`.
|
|
|
|
When async mode is available, `ai` uses this endpoint to avoid `504` failures from the blocking `/message` endpoint when the LLM takes longer than one HTTP request timeout. The submitted `messageID` identifies the user or assistant message depending on the opencode response shape; `ai` polls `GET /session/:id/message` and reads the completed assistant message.
|
|
|
|
---
|
|
|
|
### `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`:
|
|
|
|
```sh
|
|
set opencc.session_id ses_abc123
|
|
```
|
|
|
|
## TUI control
|
|
|
|
When a TUI is attached, these endpoints drive that TUI programmatically. They operate on the attached TUI prompt/dialog state, not on a specific `/session/:id`.
|
|
|
|
| Method | Path | Effect | Body |
|
|
|---|---|---|---|
|
|
| `POST` | `/tui/append-prompt` | Append text to the prompt | `{ "text": "..." }` |
|
|
| `POST` | `/tui/submit-prompt` | Submit the current prompt | none |
|
|
| `POST` | `/tui/clear-prompt` | Clear the prompt | none |
|
|
| `POST` | `/tui/open-help` | Open the help dialog | none |
|
|
| `POST` | `/tui/open-sessions` | Open the session selector | none |
|
|
| `POST` | `/tui/open-themes` | Open the theme selector | none |
|
|
| `POST` | `/tui/open-models` | Open the model selector | none |
|
|
| `POST` | `/tui/execute-command` | Execute a TUI command | `{ "command": "prompt.submit" }` |
|
|
| `POST` | `/tui/show-toast` | Show a notification | `{ "message": "...", "variant": "info" }` |
|
|
| `GET` | `/tui/control/next` | Wait for the next TUI control request | none |
|
|
| `POST` | `/tui/control/response` | Respond to a TUI control request | response body |
|
|
|
|
`/tui/show-toast` also accepts optional `title` and `duration` fields. `variant` is one of `info`, `success`, `warning`, or `error`.
|
|
|
|
Example: prefill and submit the attached TUI prompt:
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:4096/tui/append-prompt \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"text":"reply with exactly: pong"}'
|
|
|
|
curl -X POST http://127.0.0.1:4096/tui/submit-prompt
|
|
```
|
|
|
|
`POST /tui/publish` also exists as a lower-level endpoint for publishing TUI events such as `tui.prompt.append`, `tui.command.execute`, and `tui.toast.show`. Prefer the specific endpoints above unless you need that raw event surface.
|