mirror of
https://github.com/sst/opencode.git
synced 2025-08-22 14:04:07 +00:00
docs: document server API endpoints (#2019)
Co-authored-by: Jay <air@live.ca>
This commit is contained in:
Zack Jackson
GitHub
parent
40bdbf92a3
commit
c59ded82b3
3 changed files with 132 additions and 2 deletions
|
|
@ -69,7 +69,7 @@ export default defineConfig({
|
||||||
|
|
||||||
{
|
{
|
||||||
label: "Usage",
|
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"],
|
||||||
},
|
},
|
||||||
|
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -176,7 +176,7 @@ opencode run Explain the use of context in Go
|
||||||
|
|
||||||
### serve
|
### 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
|
```bash
|
||||||
opencode serve
|
opencode serve
|
||||||
|
|
|
||||||
130
packages/web/src/content/docs/docs/server.mdx
Normal file
130
packages/web/src/content/docs/docs/server.mdx
Normal file
|
|
@ -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 <number>] [--hostname <string>]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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://<hostname>:<port>/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=<pat>` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
|
||||||
|
| `GET` | `/find/file?query=<q>` | Find files by name | `string[]` (file paths) |
|
||||||
|
| `GET` | `/find/symbol?query=<q>` | Find workspace symbols | [`Symbol[]`](packages/sdk/js/src/gen/types.gen.ts) |
|
||||||
|
| `GET` | `/file?path=<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.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue