cc-libs/docs/opencode_api.md

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

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

With Basic Auth (recommended):

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:

[
  { "id": "ses_abc123", "title": "my session", "time": { "created": 1234567890, "updated": 1234567890 } }
]

---

POST /session

Create a new session.

Request body:

{ "title": "optional title", "parentID": "optional" }

Response 200:

{ "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:

{
  "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:

{
  "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.

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": "..." }.