From c59ded82b3374b5f11e7c5f1eaee4b27346f697c Mon Sep 17 00:00:00 2001 From: Zack Jackson <25274700+ScriptedAlchemy@users.noreply.github.com> Date: Tue, 19 Aug 2025 13:13:02 -0700 Subject: [PATCH] docs: document server API endpoints (#2019) Co-authored-by: Jay --- packages/web/astro.config.mjs | 2 +- packages/web/src/content/docs/docs/cli.mdx | 2 +- packages/web/src/content/docs/docs/server.mdx | 130 ++++++++++++++++++ 3 files changed, 132 insertions(+), 2 deletions(-) create mode 100644 packages/web/src/content/docs/docs/server.mdx diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs index 0ee6c4f2..da426e44 100644 --- a/packages/web/astro.config.mjs +++ b/packages/web/astro.config.mjs @@ -69,7 +69,7 @@ export default defineConfig({ { label: "Usage", - items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/github"], + items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/server", "docs/github"], }, { diff --git a/packages/web/src/content/docs/docs/cli.mdx b/packages/web/src/content/docs/docs/cli.mdx index 65d96769..6237e4eb 100644 --- a/packages/web/src/content/docs/docs/cli.mdx +++ b/packages/web/src/content/docs/docs/cli.mdx @@ -176,7 +176,7 @@ opencode run Explain the use of context in Go ### serve -Start a headless opencode server for API access. +Start a headless opencode server for API access. See [Server API](/docs/server) for the full HTTP interface. ```bash opencode serve diff --git a/packages/web/src/content/docs/docs/server.mdx b/packages/web/src/content/docs/docs/server.mdx new file mode 100644 index 00000000..90a67e6f --- /dev/null +++ b/packages/web/src/content/docs/docs/server.mdx @@ -0,0 +1,130 @@ +--- +title: Server API +description: Interact with opencode over HTTP using `opencode serve`. +--- + +## Overview + +`opencode serve` runs a headless HTTP server that exposes the same features as the TUI. The server is intended for automation and remote control. + +## Starting the server + +```bash +opencode serve [--port ] [--hostname ] +``` + +### Options + +| Flag | Short | Description | Default | +| ------------ | ----- | --------------------- | ----------- | +| `--port` | `-p` | Port to listen on | `4096` | +| `--hostname` | `-h` | Hostname to listen on | `127.0.0.1` | + +## Documentation + +The server publishes an OpenAPI 3.1 spec and an interactive explorer at: + +``` +http://:/doc +``` + +Use the spec to generate clients or inspect request and response types. All examples below use `curl` with the default `localhost:4096`. + +## API Endpoints + +### App & Config + +| Method | Path | Description | Response | +| ------ | ------------------- | --------------------------------- | -------- | +| `GET` | `/app` | Get app info | [`App`](packages/sdk/js/src/gen/types.gen.ts) | +| `POST` | `/app/init` | Initialize the app | `boolean` | +| `GET` | `/config` | Get config info | [`Config`](packages/sdk/js/src/gen/types.gen.ts) | +| `GET` | `/config/providers` | List providers and default models | `{ providers: `[`Provider[]`](packages/sdk/js/src/gen/types.gen.ts)`, default: { [key: string]: string } }` | + +### Sessions + +| Method | Path | Description | Notes | +| -------- | ---------------------------------------- | ---------------------------------- | ------------------------------------------ | +| `GET` | `/session` | List sessions | Returns [`Session[]`](packages/sdk/js/src/gen/types.gen.ts) | +| `GET` | `/session/:id` | Get session | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | +| `GET` | `/session/:id/children` | List child sessions | Returns [`Session[]`](packages/sdk/js/src/gen/types.gen.ts) | +| `POST` | `/session` | Create session | body: `{ parentID?, title? }`, returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | +| `DELETE` | `/session/:id` | Delete session | | +| `PATCH` | `/session/:id` | Update session properties | body: `{ title? }`, returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | +| `POST` | `/session/:id/init` | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }` | +| `POST` | `/session/:id/abort` | Abort a running session | | +| `POST` | `/session/:id/share` | Share session | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | +| `DELETE` | `/session/:id/share` | Unshare session | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | +| `POST` | `/session/:id/summarize` | Summarize session | | +| `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)`}[]` | +| `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)`}` | +| `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) | +| `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) | +| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID }` | +| `POST` | `/session/:id/unrevert` | Restore reverted messages | | +| `POST` | `/session/:id/permissions/:permissionID` | Respond to a permission request | body: `{ response }` | + +### Search & Files + +| Method | Path | Description | Response | +| ------ | ------------------------ | ---------------------------- | -------- | +| `GET` | `/find?pattern=` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` | +| `GET` | `/find/file?query=` | Find files by name | `string[]` (file paths) | +| `GET` | `/find/symbol?query=` | Find workspace symbols | [`Symbol[]`](packages/sdk/js/src/gen/types.gen.ts) | +| `GET` | `/file?path=` | Read a file | `{ type: "raw" \| "patch", content: string }` | +| `GET` | `/file/status` | Get status for tracked files | [`File[]`](packages/sdk/js/src/gen/types.gen.ts) | + +### Logging + +| Method | Path | Description | Response | +| ------ | ------ | ---------------------------------------------------------------- | -------- | +| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` | + +### Agents + +| Method | Path | Description | Response | +| ------ | -------- | ------------------------ | -------- | +| `GET` | `/agent` | List all available agents | [`Agent[]`](packages/sdk/js/src/gen/types.gen.ts) | + +### TUI Control + +| Method | Path | Description | Response | +| ------------ | ---------------------- | ------------------------------------------- | -------- | +| `POST` | `/tui/append-prompt` | Append text to the prompt | `boolean` | +| `POST` | `/tui/open-help` | Open the help dialog | `boolean` | +| `POST` | `/tui/open-sessions` | Open the session selector | `boolean` | +| `POST` | `/tui/open-themes` | Open the theme selector | `boolean` | +| `POST` | `/tui/open-models` | Open the model selector | `boolean` | +| `POST` | `/tui/submit-prompt` | Submit the current prompt | `boolean` | +| `POST` | `/tui/clear-prompt` | Clear the prompt | `boolean` | +| `POST` | `/tui/execute-command` | Execute a command (`{ command }`) | `boolean` | +| `POST` | `/tui/show-toast` | Show toast (`{ title?, message, variant }`) | `boolean` | +| `GET` | `/tui/control/next` | Wait for the next control request | Control request object | +| `POST` | `/tui/control/response` | Respond to a control request (`{ body }`) | `boolean` | + +### Authentication + +| Method | Path | Description | Response | +| ------ | ----------- | ---------------------------------------------------------------- | -------- | +| `PUT` | `/auth/:id` | Set authentication credentials. Body must match provider schema | `boolean` | + +### Events + +| Method | Path | Description | Response | +| ------ | -------- | ------------------------------------------------------------------------------ | -------- | +| `GET` | `/event` | Server-sent events stream. First event is `server.connected`, then bus events | Server-sent events stream | + +### Documentation + +| Method | Path | Description | Response | +| ------ | ------ | ------------------------------------- | -------- | +| `GET` | `/doc` | OpenAPI 3.1 specification and explorer | HTML page with OpenAPI spec and Swagger UI | + +## Example + +```bash +# fetch current app info +curl http://localhost:4096/app +``` + +Use the OpenAPI spec for complete schemas and additional endpoints.