API Endpoints Reference
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Open Claude Cowork backend provides a RESTful API designed to facilitate real-time, agentic conversations between a desktop client and various AI model providers. The API acts as an orchestration layer, managing sessions, integrating with the Composio Tool Router via MCP (Model Context Protocol), and streaming normalized responses to the frontend using Server-Sent Events (SSE).
The primary purpose of these endpoints is to abstract the complexities of multi-provider SDKs (Claude Agent SDK and Opencode SDK) and provide a unified interface for the Electron-based renderer. This includes handling chat message processing, request abortion, provider discovery, and health monitoring.
Sources: README.md, server/server.js:14-20
Core Chat API
The system's core functionality is centered around the /api/chat endpoint, which manages the lifecycle of an AI agent's response, including tool use and multi-turn reasoning.
POST /api/chat
This endpoint initiates or continues a conversation. It utilizes a pluggable provider system to route requests to either Anthropic's Claude or the Opencode platform.
Request Body Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
message | String | Yes | The user's prompt or input text. |
chatId | String | Yes | Unique identifier for the chat session to maintain context. |
userId | String | No | Identifier for the user (defaults to default-user). |
provider | String | No | AI provider to use (claude or opencode). |
model | String | No | Specific model ID for the selected provider. |
Sources: server/server.js:63-75, renderer/renderer.js:585-595
Streaming Logic and Data Flow
The chat endpoint implements Server-Sent Events (SSE) to provide token-by-token updates and real-time tool call visualization. It utilizes a heartbeat mechanism every 15 seconds to prevent connection timeouts.
The server pre-initializes a Composio session on startup and dynamically updates server/opencode.json with remote MCP configurations to enable tool access for the Opencode provider.
Sources: server/server.js:28-55, server/server.js:84-110, server/server.js:132-152
Management and Utility Endpoints
These endpoints support the operational requirements of the desktop application, such as interrupting long-running agent tasks and identifying available capabilities.
POST /api/abort
Used to immediately terminate an active query and its associated SDK processing for a specific chat.
| Parameter | Type | Required | Description |
|---|---|---|---|
chatId | String | Yes | The ID of the chat whose query should be aborted. |
provider | String | No | The provider associated with the active query. |
Sources: server/server.js:174-180
GET /api/providers
Returns a list of all initialized and available AI providers currently supported by the backend instance.
Response Example:
{
"providers": ["claude", "opencode"],
"default": "claude"
}
Sources: server/server.js:203-209
GET /api/health
A basic health check endpoint used by the Electron app to verify connectivity and view system status.
Sources: server/server.js:212-218
Provider Implementation Details
The API relies on standardized internal provider classes that normalize outputs from different SDKs into the SSE format consumed by the frontend.
Opencode Provider Normalization
The OpencodeProvider maps Opencode event types (e.g., message.part.updated) to the standard API chunk format.
// server/providers/opencode-provider.js
if (part?.type === 'text' && part?.text) {
yield {
type: 'text',
content: delta,
provider: this.name
};
} else if (part?.type === 'reasoning') {
yield {
type: 'text',
content: delta,
provider: this.name,
isReasoning: true
};
}
Sources: server/providers/opencode-provider.js:180-205
Response Chunk Types
The frontend handles several standardized event types received from the /api/chat stream:
| Type | Description | Derived from |
|---|---|---|
text | Standard LLM response content. | Claude/Opencode text parts |
tool_use | Indicates the agent is calling an external function. | Claude/Opencode tool invocation |
tool_result | Contains the output of an executed tool. | MCP Tool responses |
error | Contains error messages if the stream fails. | Provider catch blocks |
Sources: renderer/renderer.js:640-720, server/providers/opencode-provider.js:315-345
Summary
The Open Claude Cowork API provides a robust bridge between the user interface and agentic AI services. By combining Express.js middleware for SSE management with a modular provider architecture, the system ensures that complex tool-calling workflows and reasoning processes are delivered efficiently to the desktop application. Key integrations with Composio and the Model Context Protocol (MCP) allow these endpoints to expose over 500 external tools through a unified streaming interface.