Skip to content

Commit c59ded8

Browse files
ScriptedAlchemyjayair
ScriptedAlchemy
and
jayair
authored
docs: document server API endpoints (sst#2019)
Co-authored-by: Jay <air@live.ca>
1 parent 40bdbf9 commit c59ded8

File tree

3 files changed

+132
-2
lines changed

3 files changed

+132
-2
lines changed

‎packages/web/astro.config.mjs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ export default defineConfig({
6969

7070
{
7171
label: "Usage",
72-
items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/github"],
72+
items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/server", "docs/github"],
7373
},
7474

7575
{

‎packages/web/src/content/docs/docs/cli.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ opencode run Explain the use of context in Go
176176

177177
### serve
178178

179-
Start a headless opencode server for API access.
179+
Start a headless opencode server for API access. See [Server API](/docs/server) for the full HTTP interface.
180180

181181
```bash
182182
opencode serve

‎packages/web/src/content/docs/docs/server.mdx

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: Server API
3+
description: Interact with opencode over HTTP using `opencode serve`.
4+
---
5+
6+
## Overview
7+
8+
`opencode serve` runs a headless HTTP server that exposes the same features as the TUI. The server is intended for automation and remote control.
9+
10+
## Starting the server
11+
12+
```bash
13+
opencode serve [--port <number>] [--hostname <string>]
14+
```
15+
16+
### Options
17+
18+
| Flag | Short | Description | Default |
19+
| ------------ | ----- | --------------------- | ----------- |
20+
| `--port` | `-p` | Port to listen on | `4096` |
21+
| `--hostname` | `-h` | Hostname to listen on | `127.0.0.1` |
22+
23+
## Documentation
24+
25+
The server publishes an OpenAPI 3.1 spec and an interactive explorer at:
26+
27+
```
28+
http://<hostname>:<port>/doc
29+
```
30+
31+
Use the spec to generate clients or inspect request and response types. All examples below use `curl` with the default `localhost:4096`.
32+
33+
## API Endpoints
34+
35+
### App & Config
36+
37+
| Method | Path | Description | Response |
38+
| ------ | ------------------- | --------------------------------- | -------- |
39+
| `GET` | `/app` | Get app info | [`App`](packages/sdk/js/src/gen/types.gen.ts) |
40+
| `POST` | `/app/init` | Initialize the app | `boolean` |
41+
| `GET` | `/config` | Get config info | [`Config`](packages/sdk/js/src/gen/types.gen.ts) |
42+
| `GET` | `/config/providers` | List providers and default models | `{ providers: `[`Provider[]`](packages/sdk/js/src/gen/types.gen.ts)`, default: { [key: string]: string } }` |
43+
44+
### Sessions
45+
46+
| Method | Path | Description | Notes |
47+
| -------- | ---------------------------------------- | ---------------------------------- | ------------------------------------------ |
48+
| `GET` | `/session` | List sessions | Returns [`Session[]`](packages/sdk/js/src/gen/types.gen.ts) |
49+
| `GET` | `/session/:id` | Get session | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) |
50+
| `GET` | `/session/:id/children` | List child sessions | Returns [`Session[]`](packages/sdk/js/src/gen/types.gen.ts) |
51+
| `POST` | `/session` | Create session | body: `{ parentID?, title? }`, returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) |
52+
| `DELETE` | `/session/:id` | Delete session | |
53+
| `PATCH` | `/session/:id` | Update session properties | body: `{ title? }`, returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) |
54+
| `POST` | `/session/:id/init` | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }` |
55+
| `POST` | `/session/:id/abort` | Abort a running session | |
56+
| `POST` | `/session/:id/share` | Share session | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) |
57+
| `DELETE` | `/session/:id/share` | Unshare session | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) |
58+
| `POST` | `/session/:id/summarize` | Summarize session | |
59+
| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `[`Message`](packages/sdk/js/src/gen/types.gen.ts)`, parts: `[`Part[]`](packages/sdk/js/src/gen/types.gen.ts)`}[]` |
60+
| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `[`Message`](packages/sdk/js/src/gen/types.gen.ts)`, parts: `[`Part[]`](packages/sdk/js/src/gen/types.gen.ts)`}` |
61+
| `POST` | `/session/:id/message` | Send chat message | body matches [`ChatInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L358), returns [`Message`](packages/sdk/js/src/gen/types.gen.ts) |
62+
| `POST` | `/session/:id/shell` | Run a shell command | body matches [`CommandInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L1007), returns [`Message`](packages/sdk/js/src/gen/types.gen.ts) |
63+
| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID }` |
64+
| `POST` | `/session/:id/unrevert` | Restore reverted messages | |
65+
| `POST` | `/session/:id/permissions/:permissionID` | Respond to a permission request | body: `{ response }` |
66+
67+
### Search & Files
68+
69+
| Method | Path | Description | Response |
70+
| ------ | ------------------------ | ---------------------------- | -------- |
71+
| `GET` | `/find?pattern=<pat>` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
72+
| `GET` | `/find/file?query=<q>` | Find files by name | `string[]` (file paths) |
73+
| `GET` | `/find/symbol?query=<q>` | Find workspace symbols | [`Symbol[]`](packages/sdk/js/src/gen/types.gen.ts) |
74+
| `GET` | `/file?path=<path>` | Read a file | `{ type: "raw" \| "patch", content: string }` |
75+
| `GET` | `/file/status` | Get status for tracked files | [`File[]`](packages/sdk/js/src/gen/types.gen.ts) |
76+
77+
### Logging
78+
79+
| Method | Path | Description | Response |
80+
| ------ | ------ | ---------------------------------------------------------------- | -------- |
81+
| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` |
82+
83+
### Agents
84+
85+
| Method | Path | Description | Response |
86+
| ------ | -------- | ------------------------ | -------- |
87+
| `GET` | `/agent` | List all available agents | [`Agent[]`](packages/sdk/js/src/gen/types.gen.ts) |
88+
89+
### TUI Control
90+
91+
| Method | Path | Description | Response |
92+
| ------------ | ---------------------- | ------------------------------------------- | -------- |
93+
| `POST` | `/tui/append-prompt` | Append text to the prompt | `boolean` |
94+
| `POST` | `/tui/open-help` | Open the help dialog | `boolean` |
95+
| `POST` | `/tui/open-sessions` | Open the session selector | `boolean` |
96+
| `POST` | `/tui/open-themes` | Open the theme selector | `boolean` |
97+
| `POST` | `/tui/open-models` | Open the model selector | `boolean` |
98+
| `POST` | `/tui/submit-prompt` | Submit the current prompt | `boolean` |
99+
| `POST` | `/tui/clear-prompt` | Clear the prompt | `boolean` |
100+
| `POST` | `/tui/execute-command` | Execute a command (`{ command }`) | `boolean` |
101+
| `POST` | `/tui/show-toast` | Show toast (`{ title?, message, variant }`) | `boolean` |
102+
| `GET` | `/tui/control/next` | Wait for the next control request | Control request object |
103+
| `POST` | `/tui/control/response` | Respond to a control request (`{ body }`) | `boolean` |
104+
105+
### Authentication
106+
107+
| Method | Path | Description | Response |
108+
| ------ | ----------- | ---------------------------------------------------------------- | -------- |
109+
| `PUT` | `/auth/:id` | Set authentication credentials. Body must match provider schema | `boolean` |
110+
111+
### Events
112+
113+
| Method | Path | Description | Response |
114+
| ------ | -------- | ------------------------------------------------------------------------------ | -------- |
115+
| `GET` | `/event` | Server-sent events stream. First event is `server.connected`, then bus events | Server-sent events stream |
116+
117+
### Documentation
118+
119+
| Method | Path | Description | Response |
120+
| ------ | ------ | ------------------------------------- | -------- |
121+
| `GET` | `/doc` | OpenAPI 3.1 specification and explorer | HTML page with OpenAPI spec and Swagger UI |
122+
123+
## Example
124+
125+
```bash
126+
# fetch current app info
127+
curl http://localhost:4096/app
128+
```
129+
130+
Use the OpenAPI spec for complete schemas and additional endpoints.

0 commit comments

Comments
 (0)