diff options
| author | Cody Rayment <[email protected]> | 2025-12-06 13:28:02 -0700 |
|---|---|---|
| committer | GitHub <[email protected]> | 2025-12-06 14:28:02 -0600 |
| commit | 55981205daec8c811e7f233060dd546cfda18c5a (patch) | |
| tree | 69621f61888e6c52b3a87d71a4627fd31b87989b /packages/web/src | |
| parent | c1e6037bda84c6744d954c1b72bb43c49ad6eab3 (diff) | |
| download | opencode-55981205daec8c811e7f233060dd546cfda18c5a.tar.gz opencode-55981205daec8c811e7f233060dd546cfda18c5a.zip | |
docs: update server API reference with complete endpoint list (#5136)
Diffstat (limited to 'packages/web/src')
| -rw-r--r-- | packages/web/src/content/docs/server.mdx | 147 |
1 files changed, 113 insertions, 34 deletions
diff --git a/packages/web/src/content/docs/server.mdx b/packages/web/src/content/docs/server.mdx index 3d880fb7c..60aff2003 100644 --- a/packages/web/src/content/docs/server.mdx +++ b/packages/web/src/content/docs/server.mdx @@ -68,46 +68,104 @@ The opencode server exposes the following APIs. --- -### App +### Global Events -| Method | Path | Description | Response | -| ------ | ----------- | ------------------ | --------------------------------------- | -| `GET` | `/app` | Get app info | <a href={typesUrl}><code>App</code></a> | -| `POST` | `/app/init` | Initialize the app | `boolean` | +| Method | Path | Description | Response | +| ------ | --------------- | ------------------------------ | ------------ | +| `GET` | `/global/event` | Get global events (SSE stream) | Event stream | + +--- + +### Project + +| Method | Path | Description | Response | +| ------ | ------------------ | ----------------------- | --------------------------------------------- | +| `GET` | `/project` | List all projects | <a href={typesUrl}><code>Project[]</code></a> | +| `GET` | `/project/current` | Get the current project | <a href={typesUrl}><code>Project</code></a> | + +--- + +### Path & VCS + +| Method | Path | Description | Response | +| ------ | ------- | ------------------------------------ | ------------------------------------------- | +| `GET` | `/path` | Get the current path | <a href={typesUrl}><code>Path</code></a> | +| `GET` | `/vcs` | Get VCS info for the current project | <a href={typesUrl}><code>VcsInfo</code></a> | + +--- + +### Instance + +| Method | Path | Description | Response | +| ------ | ------------------- | ---------------------------- | --------- | +| `POST` | `/instance/dispose` | Dispose the current instance | `boolean` | --- ### Config -| Method | Path | Description | Response | -| ------ | ------------------- | --------------------------------- | ---------------------------------------------------------------------------------------- | -| `GET` | `/config` | Get config info | <a href={typesUrl}><code>Config</code></a> | -| `GET` | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` | +| Method | Path | Description | Response | +| ------- | ------------------- | --------------------------------- | ---------------------------------------------------------------------------------------- | +| `GET` | `/config` | Get config info | <a href={typesUrl}><code>Config</code></a> | +| `PATCH` | `/config` | Update config | <a href={typesUrl}><code>Config</code></a> | +| `GET` | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` | + +--- + +### Provider + +| Method | Path | Description | Response | +| ------ | -------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------- | +| `GET` | `/provider` | List all providers | `{ all: `<a href={typesUrl}>Provider[]</a>`, default: {...}, connected: string[] }` | +| `GET` | `/provider/auth` | Get provider authentication methods | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }` | +| `POST` | `/provider/{id}/oauth/authorize` | Authorize a provider using OAuth | <a href={typesUrl}><code>ProviderAuthAuthorization</code></a> | +| `POST` | `/provider/{id}/oauth/callback` | Handle OAuth callback for a provider | `boolean` | --- ### Sessions -| Method | Path | Description | Notes | -| -------- | ---------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `GET` | `/session` | List sessions | Returns <a href={typesUrl}><code>Session[]</code></a> | -| `GET` | `/session/:id` | Get session | Returns <a href={typesUrl}><code>Session</code></a> | -| `GET` | `/session/:id/children` | List child sessions | Returns <a href={typesUrl}><code>Session[]</code></a> | -| `POST` | `/session` | Create session | body: `{ parentID?, title? }`, returns <a href={typesUrl}><code>Session</code></a> | -| `DELETE` | `/session/:id` | Delete session | | -| `PATCH` | `/session/:id` | Update session properties | body: `{ title? }`, returns <a href={typesUrl}><code>Session</code></a> | -| `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 <a href={typesUrl}><code>Session</code></a> | -| `DELETE` | `/session/:id/share` | Unshare session | Returns <a href={typesUrl}><code>Session</code></a> | -| `POST` | `/session/:id/summarize` | Summarize session | | -| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` | -| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` | -| `POST` | `/session/:id/message` | Send chat message | body matches [`ChatInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L358). Optional `noReply: true` skips AI inference and returns UserMessage. Returns <a href={typesUrl}><code>Message</code></a> | -| `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 <a href={typesUrl}><code>Message</code></a> | -| `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 }` | +| Method | Path | Description | Notes | +| -------- | ---------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------- | +| `GET` | `/session` | List all sessions | Returns <a href={typesUrl}><code>Session[]</code></a> | +| `POST` | `/session` | Create a new session | body: `{ parentID?, title? }`, returns <a href={typesUrl}><code>Session</code></a> | +| `GET` | `/session/status` | Get session status for all sessions | Returns `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }` | +| `GET` | `/session/:id` | Get session details | Returns <a href={typesUrl}><code>Session</code></a> | +| `DELETE` | `/session/:id` | Delete a session and all its data | Returns `boolean` | +| `PATCH` | `/session/:id` | Update session properties | body: `{ title? }`, returns <a href={typesUrl}><code>Session</code></a> | +| `GET` | `/session/:id/children` | Get a session's child sessions | Returns <a href={typesUrl}><code>Session[]</code></a> | +| `GET` | `/session/:id/todo` | Get the todo list for a session | Returns <a href={typesUrl}><code>Todo[]</code></a> | +| `POST` | `/session/:id/init` | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }`, returns `boolean` | +| `POST` | `/session/:id/fork` | Fork an existing session at a message | body: `{ messageID? }`, returns <a href={typesUrl}><code>Session</code></a> | +| `POST` | `/session/:id/abort` | Abort a running session | Returns `boolean` | +| `POST` | `/session/:id/share` | Share a session | Returns <a href={typesUrl}><code>Session</code></a> | +| `DELETE` | `/session/:id/share` | Unshare a session | Returns <a href={typesUrl}><code>Session</code></a> | +| `GET` | `/session/:id/diff` | Get the diff for this session | query: `messageID?`, returns <a href={typesUrl}><code>FileDiff[]</code></a> | +| `POST` | `/session/:id/summarize` | Summarize the session | body: `{ providerID, modelID }`, returns `boolean` | +| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID, partID? }`, returns `boolean` | +| `POST` | `/session/:id/unrevert` | Restore all reverted messages | Returns `boolean` | +| `POST` | `/session/:id/permissions/:permissionID` | Respond to a permission request | body: `{ response, remember? }`, returns `boolean` | + +--- + +### Messages + +| Method | Path | Description | Notes | +| ------ | --------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GET` | `/session/:id/message` | List messages in a session | query: `limit?`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` | +| `POST` | `/session/:id/message` | Send a message and wait for response | body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` | +| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` | +| `POST` | `/session/:id/prompt_async` | Send a message asynchronously (no wait) | body: same as `/session/:id/message`, returns `204 No Content` | +| `POST` | `/session/:id/command` | Execute a slash command | body: `{ messageID?, agent?, model?, command, arguments }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` | +| `POST` | `/session/:id/shell` | Run a shell command | body: `{ agent, model?, command }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` | + +--- + +### Commands + +| Method | Path | Description | Response | +| ------ | ---------- | ----------------- | --------------------------------------------- | +| `GET` | `/command` | List all commands | <a href={typesUrl}><code>Command[]</code></a> | --- @@ -118,16 +176,29 @@ The opencode server exposes the following APIs. | `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 | <a href={typesUrl}><code>Symbol[]</code></a> | -| `GET` | `/file?path=<path>` | Read a file | `{ type: "raw" \| "patch", content: string }` | +| `GET` | `/file?path=<path>` | List files and directories | <a href={typesUrl}><code>FileNode[]</code></a> | +| `GET` | `/file/content?path=<p>` | Read a file | <a href={typesUrl}><code>FileContent</code></a> | | `GET` | `/file/status` | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a> | --- -### Logging +### Tools (Experimental) -| Method | Path | Description | Response | -| ------ | ------ | ------------------------------------------------------------ | --------- | -| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` | +| Method | Path | Description | Response | +| ------ | ------------------------------------------- | ---------------------------------------- | -------------------------------------------- | +| `GET` | `/experimental/tool/ids` | List all tool IDs | <a href={typesUrl}><code>ToolIDs</code></a> | +| `GET` | `/experimental/tool?provider=<p>&model=<m>` | List tools with JSON schemas for a model | <a href={typesUrl}><code>ToolList</code></a> | + +--- + +### LSP, Formatters & MCP + +| Method | Path | Description | Response | +| ------ | ------------ | -------------------------- | -------------------------------------------------------- | +| `GET` | `/lsp` | Get LSP server status | <a href={typesUrl}><code>LSPStatus[]</code></a> | +| `GET` | `/formatter` | Get formatter status | <a href={typesUrl}><code>FormatterStatus[]</code></a> | +| `GET` | `/mcp` | Get MCP server status | `{ [name: string]: `<a href={typesUrl}>MCPStatus</a>` }` | +| `POST` | `/mcp` | Add MCP server dynamically | body: `{ name, config }`, returns MCP status object | --- @@ -139,6 +210,14 @@ The opencode server exposes the following APIs. --- +### Logging + +| Method | Path | Description | Response | +| ------ | ------ | ------------------------------------------------------------ | --------- | +| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` | + +--- + ### TUI | Method | Path | Description | Response | |