### WindsurfAPI Manual Installation

Source: https://github.com/dwgx/windsurfapi/blob/master/README.en.md

Detailed steps for manually installing WindsurfAPI, including language server setup, environment configuration, and starting the application.

```bash
git clone https://github.com/dwgx/WindsurfAPI.git
cd WindsurfAPI

# Language Server binary — auto-detects Linux/macOS, one-click download + chmod
bash install-ls.sh

# Download chain: WindsurfAPI release → public LS mirror
#   https://github.com/dwgx/windsurf-ls-release/releases/latest/download
# → Exafunction/codeium fallback. For a private mirror or rollback, set:
#   WINDSURFAPI_LS_RELEASE=https://github.com/<owner>/<repo>/releases/latest/download bash install-ls.sh

# Default install paths:
#   Linux x64:           /opt/windsurf/language_server_linux_x64
#   Linux arm64:         /opt/windsurf/language_server_linux_arm
#   macOS Apple Silicon: $HOME/.windsurf/language_server_macos_arm
#   macOS Intel:         $HOME/.windsurf/language_server_macos_x64

# Or use a local binary you already have:
#   bash install-ls.sh /path/to/language_server_linux_x64
# Or specify a custom URL:
#   bash install-ls.sh --url https://example.com/language_server_linux_x64

# ⚠️ Can't see opus-4.7 / other new models?
The default download chain now uses the dwgx/windsurf-ls-release public mirror.
If the mirror does not cover your platform yet, copy the LS binary out of
the Windsurf desktop app bundle:
#
#   macOS:   "$HOME/Library/Application Support/Windsurf/resources/app/extensions/windsurf/bin/language_server_macos_arm"
#   Linux:   "$HOME/.windsurf/bin/language_server_linux_x64"
#            or /opt/Windsurf/resources/app/extensions/windsurf/bin/language_server_linux_x64
#   Windows: %APPDATA%\Windsurf\bin\language_server_windows_x64.exe
#
#   # Install from the local desktop copy:
#   bash install-ls.sh /path/to/language_server_linux_x64
#
# Once swapped, /v1/models will auto-discover the newer catalog from the cloud.

cat > .env << 'EOF'
PORT=3003
API_KEY=
DEFAULT_MODEL=claude-4.5-sonnet-thinking
MAX_TOKENS=8192
LOG_LEVEL=info
LS_BINARY_PATH=/opt/windsurf/language_server_linux_x64
LS_DATA_DIR=/opt/windsurf/data
LS_PORT=42100
DASHBOARD_PASSWORD=
EOF

# For a local macOS run, use the LS_BINARY_PATH printed by install-ls.sh
# and set LS_DATA_DIR to a user-writable path such as /Users/you/.windsurf/data.

# Note: Inline comments are supported in .env for unquoted values:
#   PORT=3003  # Service port
# Quoted values preserve everything inside the quotes.

node src/index.js
```

--------------------------------

### One-Click Deployment of WindsurfAPI

Source: https://github.com/dwgx/windsurfapi/blob/master/README.md

Use this method for a quick setup. It clones the repository, sets up directories and permissions, generates the .env file, and starts the API. Access the dashboard at http://your-ip:3003/dashboard.

```bash
git clone https://github.com/dwgx/WindsurfAPI.git
cd WindsurfAPI
bash setup.sh          # 建目录 · 配权限 · 生成 .env
node src/index.js
```

--------------------------------

### Manual Installation of WindsurfAPI

Source: https://github.com/dwgx/windsurfapi/blob/master/README.md

Install WindsurfAPI manually by cloning the repository and running the installation script for the language server. This method allows for custom configurations, including specifying the language server binary path or download URL.

```bash
git clone https://github.com/dwgx/WindsurfAPI.git
cd WindsurfAPI

# Language Server 二进制 —— 自动检测 Linux/macOS，一键下载 + chmod
bash install-ls.sh

# 下载链：WindsurfAPI release → 公开 LS mirror
#   https://github.com/dwgx/windsurf-ls-release/releases/latest/download
# → Exafunction/codeium fallback。需要私有镜像或回滚时可设置：
#   WINDSURFAPI_LS_RELEASE=https://github.com/<owner>/<repo>/releases/latest/download bash install-ls.sh

# 默认安装路径：
#   Linux x64:          /opt/windsurf/language_server_linux_x64
#   Linux arm64:        /opt/windsurf/language_server_linux_arm
#   macOS Apple Silicon: $HOME/.windsurf/language_server_macos_arm
#   macOS Intel:        $HOME/.windsurf/language_server_macos_x64

# 如果想用本地已下好的 binary：
#   bash install-ls.sh /path/to/language_server_linux_x64
# 或者指定 URL：
#   bash install-ls.sh --url https://example.com/language_server_linux_x64

# ⚠️ 看不到 opus-4.7 / 其他新模型？
# 默认下载链已接入 dwgx/windsurf-ls-release 公开 mirror。
# 如果 mirror 暂未覆盖你的平台，仍可把 Windsurf 桌面端本体里的 LS binary 拷过来：
#
#   macOS:   "$HOME/Library/Application Support/Windsurf/resources/app/extensions/windsurf/bin/language_server_macos_arm"
#   Linux:   "$HOME/.windsurf/bin/language_server_linux_x64"
#            或  /opt/Windsurf/resources/app/extensions/windsurf/bin/language_server_linux_x64
#   Windows: %APPDATA%\Windsurf\bin\language_server_windows_x64.exe
#
#   # 从本地桌面端装：
#   bash install-ls.sh /path/to/language_server_linux_x64
#
# LS binary 一换，/v1/models 立刻就能看到最新模型目录了（云端自动发现）。

cat > .env << 'EOF'
PORT=3003
API_KEY=
DEFAULT_MODEL=claude-4.5-sonnet-thinking
MAX_TOKENS=8192
LOG_LEVEL=info
LS_BINARY_PATH=/opt/windsurf/language_server_linux_x64
LS_DATA_DIR=/opt/windsurf/data
LS_PORT=42100
DASHBOARD_PASSWORD=
EOF

# macOS 本地部署时，使用 install-ls.sh 打印的 LS_BINARY_PATH，
# 并把 LS_DATA_DIR 设到用户可写目录，例如 /Users/you/.windsurf/data。

node src/index.js
```

--------------------------------

### Start the HTTPS proxy

Source: https://github.com/dwgx/windsurfapi/blob/master/local-setup.md

Starts the Node.js HTTPS proxy server. This command will output the URLs where the proxy is accessible, including localhost and your LAN IP.

```bash
node https-proxy.js
```

--------------------------------

### Install mkcert using Homebrew

Source: https://github.com/dwgx/windsurfapi/blob/master/local-setup.md

Installs the mkcert tool, which is used for generating locally trusted certificates. This command is for macOS systems using Homebrew.

```bash
brew install mkcert
```

--------------------------------

### Request with Tool Definition

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/tool-emulation.md

Example JSON structure for a request that includes tool definitions.

```json
{
  "messages": [...],
  "tools": [
    {"type": "function", "function": {"name": "bash", ...}}
  ]
}
```

--------------------------------

### Install local CA on another PC (macOS)

Source: https://github.com/dwgx/windsurfapi/blob/master/local-setup.md

Installs the mkcert root CA certificate on another macOS machine to trust the locally generated certificates. This is necessary for accessing the HTTPS proxy from different devices on the same network.

```bash
mkcert -CAROOT
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain rootCA.pem
```

--------------------------------

### Messages API Tool Call Streaming Example

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Example JSON events for streaming tool calls. Shows the start of a tool use block and partial JSON deltas for the tool's input.

```json
{"type": "content_block_start", "content_block": {"type": "tool_use", "id": "tool_123", "name": "bash"}}
```

```json
{"type": "content_block_delta", "delta": {"type": "input_json_delta", "partial_json": "{\"command"}}
```

```json
{"type": "content_block_stop"}
```

--------------------------------

### Install mkcert local CA

Source: https://github.com/dwgx/windsurfapi/blob/master/local-setup.md

Installs the mkcert-generated Certificate Authority (CA) into your system's trust store. This allows your system to trust certificates generated by mkcert.

```bash
sudo mkcert -install
```

--------------------------------

### WindsurfAPI Docker Deployment

Source: https://github.com/dwgx/windsurfapi/blob/master/README.en.md

Instructions for deploying WindsurfAPI using Docker Compose, including environment variable setup and log monitoring.

```bash
cp .env.example .env

# Optional: place language_server_linux_x64 under .docker-data/opt/windsurf/
# If omitted, the container will auto-download it into /opt/windsurf/ on first boot.

docker compose up -d --build
docker compose logs -f
```

--------------------------------

### Build Start Cascade Request

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/windsurf-client.md

Constructs a Protobuf request message for initiating a Cascade conversation. It accepts various options to configure the conversation.

```APIDOC
## buildStartCascadeRequest

### Description
Builds the request to start a Cascade conversation.

### Parameters
#### Options
```typescript
interface CascadeStartOptions {
  model: {
    modelUid: string;
    credit: number;
  };
  messages: Array<{role, content}>;
  systemPrompt?: string;
  tools?: Array<{name, description, parameters}>;
  maxTokens?: number;
  temperature?: number;
  // ... other parameters
}
```

### Returns
Encoded Protobuf buffer.
```

--------------------------------

### Build Start Cascade Request

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/windsurf-client.md

Constructs the Protobuf message for initiating a Cascade conversation. Requires model details and initial messages.

```typescript
interface CascadeStartOptions {
  model: {
    modelUid: string;
    credit: number;
  };
  messages: Array<{role, content}>;
  systemPrompt?: string;
  tools?: Array<{name, description, parameters}>;
  maxTokens?: number;
  temperature?: number;
  // ... 其他参数
}
```

--------------------------------

### Cache Reset Error Example

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/errors.md

This is an example of the Anthropic error format for a cache reset. It indicates that the prompt cache has been reset and suggests retrying without cache control.

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Prompt cache has been reset. Try again without cache_control."
  }
}
```

--------------------------------

### Run HTTPS proxy with custom ports

Source: https://github.com/dwgx/windsurfapi/blob/master/local-setup.md

Starts the Node.js HTTPS proxy using custom environment variables for the HTTPS port and the target backend port. This allows flexibility if the default ports are in use.

```bash
HTTPS_PORT=8443 TARGET_PORT=3003 node https-proxy.js
```

--------------------------------

### Model Credit Cost Examples

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/models.md

Illustrates the credit cost multiplier for various models from Anthropic, OpenAI, and other providers. Used to calculate account quota consumption.

```javascript
// Anthropic
MODELS['claude-4.5-haiku'].credit        // 1 (最便宜)
MODELS['claude-4.5-sonnet'].credit       // 2
MODELS['claude-opus-4.6'].credit         // 6
MODELS['claude-opus-4-7-xhigh'].credit   // 12

// OpenAI
MODELS['gpt-4o'].credit                  // 1
MODELS['gpt-5.1-medium'].credit          // 1
MODELS['gpt-5.2-high'].credit            // 3
MODELS['gpt-5.2-xhigh'].credit           // 8

// 免费/轻量
MODELS['glm-4.7'].credit                 // 0.5
MODELS['qwen-3'].credit                  // 0.5
```

--------------------------------

### Build Get Trajectory Steps Request

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/windsurf-client.md

Builds the Protobuf request to retrieve specific steps from a conversation trajectory.

```javascript
function buildGetTrajectoryStepsRequest(conversationId, stepIndices)
```

--------------------------------

### Enabling Auto Update via cURL

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.67.md

This example demonstrates how to enable the quiet window auto-update feature using a cURL command, targeting the dashboard API.

```APIDOC
```bash
curl -X PUT http://your-host:3888/dashboard/api/auto-update/quiet-window \
  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"enabled":true}'
```
```

--------------------------------

### ToolCallStreamParser Example

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/tool-emulation.md

Demonstrates parsing tool calls from Cascade stream responses. Use this parser to extract tool names and arguments as they arrive in the stream.

```javascript
const parser = new ToolCallStreamParser();

for await (const chunk of streamResponse) {
  const result = parser.processDelta(chunk);
  
  if (result.isToolCall) {
    console.log(`Tool: ${result.tool.name}`);
    console.log(`Args: ${result.tool.arguments}`);
  }
  
  if (result.text) {
    console.log(result.text);
  }
}
```

--------------------------------

### Proxy Configuration Error Example

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/errors.md

This JSON response indicates a proxy configuration error, specifically an invalid proxy URL format. Ensure your proxy URLs adhere to the supported formats.

```json
{
  "error": "ERR_PROXY_INVALID_FORMAT: Invalid proxy URL format"
}
```

--------------------------------

### Define gRPC Start Cascade Request

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/types.md

Specifies the structure for initiating a cascade, including conversation ID, user messages, system prompt, model details, and optional parameters like max tokens and temperature.

```typescript
interface StartCascadeRequest {
  conversationId?: string;
  userMessages: Array<{ 
    role: string;
    content: string;
  }>;
  systemPrompt?: string;
  modelUid: string;
  maxTokens?: number;
  temperature?: number;
  tools?: Array<{ 
    name: string;
    description: string;
    parameters: JSONSchema;
  }>;
}
```

--------------------------------

### Run Sharded Tests with Timeout (Shard 1)

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.140.md

Execute sharded tests with a specified timeout using npm. This example shows running shard 1 out of 4.

```bash
npm.cmd run test:shard -- 1 4 --timeout-ms=90000
```

--------------------------------

### Run Sharded Tests with Timeout (Shard 3)

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.140.md

Execute sharded tests with a specified timeout using npm. This example shows running shard 3 out of 4.

```bash
npm.cmd run test:shard -- 3 4 --timeout-ms=90000
```

--------------------------------

### WindsurfAPI One-Click Deployment

Source: https://github.com/dwgx/windsurfapi/blob/master/README.en.md

Steps to clone the repository, set up the environment, and run the WindsurfAPI application using a bash script.

```bash
git clone https://github.com/dwgx/WindsurfAPI.git
cd WindsurfAPI
bash setup.sh          # Create directories · Set permissions · Generate .env
node src/index.js
```

--------------------------------

### Messages API Streaming Events

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Example JSON payloads representing different event types during a streaming response from the Messages API. Includes message start, content block events, deltas, and stop signals.

```json
{"type": "message_start", "message": {"id": "msg_...", ...}}
```

```json
{"type": "content_block_start", "index": 0, "content_block": {"type": "text"}}
```

```json
{"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "..."}}
```

```json
{"type": "content_block_stop", "index": 0}
```

```json
{"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {...}}
```

```json
{"type": "message_stop"}
```

--------------------------------

### Initialize and Use I18n Helper

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/dashboard-i18n.md

Load locale bundles using `I18n.init()` and translate keys with `I18n.t()`. Supports translation with placeholders.

```javascript
await I18n.init('en');  // or 'zh-CN'

I18n.t('nav.overview');           // "Dashboard"
I18n.t('card.activeAccounts.title'); // "Active Accounts"

I18n.t('card.activeAccounts.subtitle', { total: 5, error: 1 });
// Result: "5 total · 1 abnormal"
```

--------------------------------

### Parse Start Cascade Response

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/windsurf-client.md

Parses the Protobuf buffer response from a Cascade start request. Extracts conversation and cascade request IDs.

```typescript
{
  conversationId: string;
  cascadeRequestId: string;
  // ... 其他字段
}
```

--------------------------------

### Run Proto Trace Tests

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.133.md

Execute the test suite for the proto-trace module using Node.js.

```bash
node --test test/proto-trace.test.js
```

--------------------------------

### Run Release Tests

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.140.md

Execute the release-specific test suite using npm.

```bash
npm.cmd run test:release
```

--------------------------------

### Parse Start Cascade Response

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/windsurf-client.md

Parses the Protobuf buffer response received after starting a Cascade conversation, extracting key information like conversation and request IDs.

```APIDOC
## parseStartCascadeResponse

### Description
Parses the response from starting a Cascade conversation.

### Returns
```typescript
{
  conversationId: string;
  cascadeRequestId: string;
  // ... other fields
}
```
```

--------------------------------

### Verify Proto Trace Module

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.133.md

Run this command to check the syntax of the proto-trace JavaScript module.

```bash
node --check src/proto-trace.js
```

--------------------------------

### Authentication Error: Missing API Key

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/errors.md

Details on the 'auth_error' when an API key is missing, including HTTP status code, example error formats, triggering conditions, and a cURL example for correction.

```APIDOC
## Authentication Error: Missing API Key

### Description
This error occurs when the API key is missing from the request, and the server is configured to run in a fail-closed mode.

### Method
N/A (This describes an error condition, not a specific API call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Error Response (401)
- **error.message** (string) - Description of the authentication error.
- **error.type** (string) - The type of error, which is 'auth_error'.

#### Response Example (OpenAI Format)
```json
{
  "error": {
    "message": "Missing API key. This server runs in fail-closed mode...",
    "type": "auth_error"
  }
}
```

#### Response Example (Anthropic Format)
```json
{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "No active accounts"
  }
}
```

### Triggering Conditions
- The service is bound to a public network address (0.0.0.0) and the request lacks an `Authorization` header or an `x-api-key` header.
- The `API_KEY` environment variable is configured, but the key provided in the request does not match.

### Resolution
Provide the API key in the request headers.

### Resolution Example
```bash
curl -H "Authorization: Bearer your_api_key" \
  http://localhost:3003/v1/messages
```
```

--------------------------------

### Load and Display Language Server Instances

Source: https://github.com/dwgx/windsurfapi/blob/master/src/dashboard/index-sketch.html

Fetches language server instances and renders them in the UI. Handles cases with no instances available.

```javascript
this.loadDrought(); const [d, ov] = await Promise.all([
  this.api('GET', '/accounts'),
  this.api('GET', '/overview').catch(() => null),
]);
const instances = ov?.langServer?.instances || [];
const poolCard = document.getElementById('ls-pool-card');
if (poolCard) {
  if (instances.length > 0) {
    poolCard.innerHTML = `<div class="section"> <div class="section-head"><div><div class="section-title"><span class="num">L</span><span>language server pool</span></div> <div class="section-desc">${instances.length} instance(s)</div></div></div> <div class="ls-pool">${instances.map(i => `<div class="ls-inst"> <div class="ls-key"><span class="ls-dot ${i.ready ? '' : 'pending'}"></span>${this.esc(i.key === 'default' ? 'default' : i.key.replace(/^px\_/, ''))}</div> <div class="ls-meta">port ${i.port} · pid ${i.pid || '-'}</div> <div class="ls-meta">${this.esc(i.proxy || 'no proxy')}</div> </div>`).join('')}</div></div>`;
  } else {
    poolCard.innerHTML = '';
  }
}
```

--------------------------------

### Enable Native Bridge Configuration

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/tool-emulation.md

Bash commands to enable the Native Bridge and specify tool whitelists.

```bash
# 启用 Native Bridge
WINDSURFAPI_NATIVE_TOOL_BRIDGE=1          # 或 "all_mapped"

# 工具白名单
WINDSURFAPI_NATIVE_TOOL_BRIDGE_TOOLS=bash,read_file,edit_file

# 灰度门（可选，为空=不限制）
WINDSURFAPI_NATIVE_TOOL_BRIDGE_MODELS=gpt-5.*,claude-*
WINDSURFAPI_NATIVE_TOOL_BRIDGE_ACCOUNTS=user@example.com
WINDSURFAPI_NATIVE_TOOL_BRIDGE_API_KEYS=sk-abc123

# 禁用开关
WINDSURFAPI_NATIVE_TOOL_BRIDGE_OFF=1      # 强制禁用
```

--------------------------------

### Get Dashboard Internationalization File

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Fetches the internationalization JSON file for a specified locale.

```APIDOC
## GET /dashboard/i18n/{locale}.json

### Description
Fetches the internationalization JSON file for a specified locale, enabling frontend multilingual support.

### Method
GET

### Endpoint
/dashboard/i18n/{locale}.json

### Parameters
#### Path Parameters
- **locale** (string) - Required - The language code (e.g., en, zh, ja).

### Response
#### Success Response (200)
- **JSON Object** - A JSON object containing translated strings for the specified locale.

### Use Case
Frontend multilingual support.
```

--------------------------------

### Curl Upstream Endpoints

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.60.md

Example of how to curl the upstream endpoints API, requiring the X-Dashboard-Password header.

```bash
curl -H 'X-Dashboard-Password: $PW' $HOST:3888/dashboard/api/upstream-endpoints
```

--------------------------------

### Run Native Bridge Docs Tests

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.138.md

Execute the native bridge documentation tests using Node.js.

```bash
node --test test/native-bridge-docs.test.js
```

--------------------------------

### Runtime Experimental Configuration (runtime-config.json)

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/configuration.md

Contains experimental runtime configurations. Settings like 'autoUpdateQuietWindow' and 'cascadeReuseByCallerEnabled' control experimental features.

```json
{
  "experimental": {
    "autoUpdateQuietWindow": false,
    "cascadeReuseByCallerEnabled": false,
    "modelAccessControl": {}
  }
}
```

--------------------------------

### Get Contributors Data

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Retrieves a JSON list of contributors, typically used for a 'thank you' panel on the dashboard.

```APIDOC
## GET /dashboard/data/contributors.json

### Description
Retrieves a JSON list of contributors. This data is often used to populate a 'thank you' panel within the dashboard.

### Method
GET

### Endpoint
/dashboard/data/contributors.json

### Response
#### Success Response (200)
- **JSON Array** - An array of contributor objects.

### Use Case
Dashboard 'thank you' panel.
```

--------------------------------

### GET /dashboard Endpoint

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Retrieves the HTML for the dashboard. This endpoint is typically accessed via a web browser.

```http
GET /dashboard
```

--------------------------------

### Add Account and Check Status

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/errors.md

Use these commands to add a new account or check the status of existing accounts when no active accounts are available.

```bash
# 添加账号
curl -X POST http://localhost:3003/auth/login \
  -H "Authorization: Bearer key" \
  -d '{ "token": "exaaip_...", "label": "my account" }'

# 或检查现有账号状态
curl -H "Authorization: Bearer key" \
  http://localhost:3003/auth/accounts
```

--------------------------------

### Relocate Release Notes Files

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.35.md

Demonstrates the relocation of release notes files from the repository root to the `docs/releases/` directory. This change is accompanied by an update to the release workflow to prioritize the new location.

```bash
RELEASE_NOTES_2.0.6.md  →  docs/releases/RELEASE_NOTES_2.0.6.md
RELEASE_NOTES_2.0.7.md  →  docs/releases/RELEASE_NOTES_2.0.7.md
...
```

--------------------------------

### Get Dashboard HTML

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Retrieves the dashboard HTML page. This endpoint is typically accessed via a web browser.

```APIDOC
## GET /dashboard

### Description
Retrieves the main dashboard HTML page. This endpoint is intended for access via a web browser.

### Method
GET

### Endpoint
/dashboard

### Parameters
#### Query Parameters
None

### Headers
#### Cookie
- **dashboard_skin** (string) - Optional - Use "sketch" for an experimental sketch style; other values use the default UI.

### Response
#### Success Response (200)
- **HTML** - The HTML content of the dashboard page.

### Use Case
Web browser access to the management interface.
```

--------------------------------

### Add Account using curl

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/README.md

Use this command to add an account to the WindsurfAPI. Ensure you replace 'your_api_key' with your actual API key and 'windsurf_token' with the token for the account.

```bash
curl -X POST http://localhost:3003/auth/login \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"token": "windsurf_token"}'
```

--------------------------------

### Build Get Trajectory Request

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/windsurf-client.md

Builds the Protobuf request to fetch the conversation trajectory (history) using the conversation ID.

```javascript
function buildGetTrajectoryRequest(conversationId, offset)
```

--------------------------------

### GET /dashboard/data/contributors.json Endpoint

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Retrieves a JSON list of contributors. Used for displaying contributor information, such as on a dashboard's 'thank you' panel.

```http
GET /dashboard/data/contributors.json
```

--------------------------------

### Proxy Configuration (proxy.json)

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/configuration.md

Defines proxy settings per account. 'global' settings apply to all accounts unless overridden. Account-specific settings in 'accounts' take precedence.

```json
{
  "global": {
    "type": "http",
    "url": "http://proxy.example.com:8080"
  },
  "accounts": {
    "acc_abc123": {
      "type": "socks5",
      "url": "socks5://proxy.example.com:1080"
    }
  }
}
```

--------------------------------

### GET /dashboard/i18n/{locale}.json Endpoint

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Fetches the internationalization JSON file for a specified locale. Used for frontend multilingual support.

```http
GET /dashboard/i18n/{locale}.json
```

--------------------------------

### Get Account Statistics

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/account-pool.md

Fetches statistics about the accounts in the pool, including active, inactive, and total counts. Useful for capacity planning.

```javascript
const counts = getAccountCount();
console.log(`${counts.activeCount}/${counts.totalCount} active`);
```

--------------------------------

### List Available Models

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Use this endpoint to enumerate all available models. This is useful for clients to understand which models they can query.

```http
GET /v1/models
```

--------------------------------

### Build Get Trajectory Request

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/windsurf-client.md

Constructs a Protobuf request to retrieve the trajectory (history) of a given conversation, using an offset for pagination.

```APIDOC
## buildGetTrajectoryRequest

### Description
Builds the request to get the trajectory (history) of a conversation.

### Parameters
- **conversationId** (string) - Required - The ID of the conversation.
- **offset** (number) - Optional - The offset for retrieving trajectory history.
```

--------------------------------

### OpenAI GPT 模型列表

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/models.md

列出了 OpenAI GPT 系列模型的可用名称，包括 GPT-4o、GPT-5 系列、GPT-5.1 系列、GPT-5.2 系列、GPT-5.4 系列和 O 系列。

```javascript
// GPT-4o
MODELS['gpt-4o']
MODELS['gpt-4.1']

// GPT-5 系列
MODELS['gpt-5']
MODELS['gpt-5-medium']
MODELS['gpt-5-high']
MODELS['gpt-5-codex']

// GPT-5.1 系列
MODELS['gpt-5.1']
MODELS['gpt-5.1-low']
MODELS['gpt-5.1-medium']
MODELS['gpt-5.1-high']
MODELS['gpt-5.1-fast']
MODELS['gpt-5.1-low-fast']
MODELS['gpt-5.1-medium-fast']
MODELS['gpt-5.1-high-fast']
MODELS['gpt-5.1-codex-low']
MODELS['gpt-5.1-codex-medium']
MODELS['gpt-5.1-codex-max-*']

// GPT-5.2 系列
MODELS['gpt-5.2']
MODELS['gpt-5.2-none']
MODELS['gpt-5.2-low']
MODELS['gpt-5.2-high']
MODELS['gpt-5.2-xhigh']
MODELS['gpt-5.2-*-fast']
MODELS['gpt-5.2-codex-*']

// GPT-5.4 系列
MODELS['gpt-5.4']
MODELS['gpt-5.4-mini-*']

// O 系列 (推理)
MODELS['o3']
MODELS['o3-mini']
MODELS['o4-mini']
```

--------------------------------

### WindsurfAPI Project File Structure

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/architecture.md

Provides a detailed breakdown of the WindsurfAPI project's directory and file organization, including the purpose of each module.

```text
WindsurfAPI/
├── src/
│   ├── index.js                    # 启动和初始化
│   ├── server.js                   # HTTP 路由和请求处理
│   ├── config.js                   # 配置加载（.env）
│   │
│   ├── handlers/                   # 协议处理程序
│   │   ├── chat.js                 # OpenAI /v1/chat/completions
│   │   ├── messages.js             # Anthropic /v1/messages
│   │   ├── responses.js            # OpenAI /v1/responses
│   │   ├── models.js               # 模型列表
│   │   ├── tool-emulation.js       # 工具仿真核心
│   │   └── intent-extractor.js     # 意图检测
│   │
│   ├── auth.js                     # 账号池和认证
│   ├── account/
│   │   └── sticky-session.js       # 粘性会话管理
│   │
│   ├── models.js                   # 模型目录
│   ├── client.js                   # WindsurfClient 主类
│   ├── windsurf.js                 # Protobuf 消息和 gRPC
│   ├── grpc.js                     # gRPC 传输层
│   ├── langserver.js               # LS 进程管理和池
│   │
│   ├── conversation-pool.js        # 对话复用池
│   ├── cache.js                    # 响应缓存
│   ├── runtime-config.js           # 运行时实验配置
│   ├── cascade-native-bridge.js    # Native Tool Bridge
│   ├── special-agent.js            # Special Agent 后端
│   ├── sanitize.js                 # 安全清理
│   │
│   ├── dashboard/                  # 管理仪表板
│   │   ├── api.js                  # 仪表板 API
│   │   ├── stats.js                # 统计和日志
│   │   ├── proxy-config.js         # 代理管理
│   │   ├── model-access.js         # 模型访问控制
│   │   ├── windsurf-login.js       # OAuth 登录
│   │   └── ...
│   │
│   └── ...
│
├── dashboard/                       # 前端 UI
│   ├── index.html                  # 默认仪表板
│   ├── index-sketch.html           # 素描风格
│   ├── i18n/                       # 国际化
│   └── css/, js/
│
└── install-ls.sh                   # LS 安装脚本
```

--------------------------------

### Run Dashboard Syntax Tests

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.138.md

Execute the dashboard syntax tests using Node.js.

```bash
node --test test/dashboard-syntax.test.js
```

--------------------------------

### Messages API Error Response

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Example JSON structure for an error response from the Messages API. Includes error type and a descriptive message.

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages is required"
  }
}
```

--------------------------------

### OpenAI Format Authentication Error

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/errors.md

Example of an authentication error in OpenAI's JSON format. This occurs when the API key is missing or invalid.

```json
{
  "error": {
    "message": "Missing API key. This server runs in fail-closed mode...",
    "type": "auth_error"
  }
}
```

--------------------------------

### WindsurfAPI Architecture Diagram

Source: https://github.com/dwgx/windsurfapi/blob/master/README.md

This diagram illustrates the architecture of WindsurfAPI, showing how it handles requests from OpenAI SDKs and Anthropic clients, translates them to gRPC, and interacts with the Windsurf Cloud.

```text
     ┌─────────────┐   /v1/chat/completions   ┌────────────┐
     │ OpenAI SDK  │ ──────────────────────→  │            │
     │ curl / 前端 │ ←──────────────────────  │            │
     └─────────────┘   OpenAI JSON + SSE      │ WindsurfAPI│
                                              │ Node.js    │      ┌──────────────┐       ┌─────────────────┐
     ┌─────────────┐   /v1/messages           │ (本服务)   │ gRPC │ Language     │ HTTPS │ Windsurf 云端   │
     │ Claude Code │ ──────────────────────→  │            │ ───→ │ Server (LS)  │ ────→ │ server.self-    │
     │ Cline       │ ←──────────────────────  │            │ ←─── │ (Windsurf    │ ←─── │ serve.windsurf  │
     │ Cursor      │   Anthropic SSE          │            │      │  binary)     │       │ .com            │
     └─────────────┘                          └────────────┘      └──────────────┘       └─────────────────┘
                                                    ↑
                                                账号池轮询
                                                速率限制隔离
                                                故障转移
```

--------------------------------

### GET /health Endpoint

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Retrieves the current health status of the service. The 'verbose' query parameter can be used to include detailed status information.

```http
GET /health
```

--------------------------------

### Verify JavaScript Source Files

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.129.md

Use the `--check` flag to verify the syntax of individual JavaScript source files before running them.

```bash
node --check src\cascade-native-bridge.js
```

```bash
node --check src\native-bridge-stats.js
```

```bash
node --check src\handlers\chat.js
```

--------------------------------

### Get Account Pool Status

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/http-endpoints.md

Retrieves the current status of the account pool, including active, inactive, and total counts. Requires authentication.

```APIDOC
## GET /auth/status

### Description
Retrieves the current status of the account pool, including active, inactive, and total counts. Requires authentication.

### Method
GET

### Endpoint
/auth/status

### Parameters
#### Request Headers
- **Authorization** (string) - Required - Bearer {API_KEY}

### Response
#### Success Response (200)
- **authenticated** (boolean) - Indicates if authentication is successful.
- **activeCount** (integer) - The number of currently active accounts.
- **inactiveCount** (integer) - The number of inactive accounts.
- **totalCount** (integer) - The total number of accounts in the pool.

### Response Example
```json
{
  "authenticated": true,
  "activeCount": 5,
  "inactiveCount": 1,
  "totalCount": 6
}
```
```

--------------------------------

### Get List of All Accounts

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/account-pool.md

Retrieves a list view of all accounts in the pool, excluding sensitive fields like tokens. Useful for monitoring and auditing.

```javascript
const accounts = getAccountList();
accounts.forEach(acc => {
  console.log(`${acc.email} (${acc.status})`);
});
```

--------------------------------

### Configure Native Bridge Trace Directory

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.113.md

In Docker deployments, set WINDSURFAPI_PROTO_TRACE_DIR to /data/proto-trace to ensure protobuf traces persist across container recreates.

```bash
WINDSURFAPI_PROTO_TRACE_DIR=/data/proto-trace
```

--------------------------------

### Build Get Trajectory Steps Request

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/windsurf-client.md

Constructs a Protobuf request to retrieve specific steps from a conversation's trajectory, identified by their indices.

```APIDOC
## buildGetTrajectoryStepsRequest

### Description
Builds the request to get specific trajectory steps from a conversation.

### Parameters
- **conversationId** (string) - Required - The ID of the conversation.
- **stepIndices** (Array<number>) - Required - An array of step indices to retrieve.
```

--------------------------------

### Docker Deployment of WindsurfAPI

Source: https://github.com/dwgx/windsurfapi/blob/master/README.md

Deploy WindsurfAPI using Docker Compose for a containerized environment. This method handles dependencies and provides persistent storage for data. Ensure the language server binary is placed in the specified directory or it will be downloaded automatically.

```bash
cp .env.example .env

# 可选：提前把 language_server_linux_x64 放到 .docker-data/opt/windsurf/ 下
# 不放也行，容器首次启动时会自动下载到 /opt/windsurf/

docker compose up -d --build
docker compose logs -f
```

--------------------------------

### Run Sharded Tests with Timeout

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.140.md

Execute sharded tests with a specified timeout using npm. This example shows running shard 0 out of 4.

```bash
npm.cmd run test:shard -- 0 4 --timeout-ms=90000
```

--------------------------------

### Run Cache Tests

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.138.md

Execute the cache-related tests using Node.js.

```bash
node --test test/cache.test.js
```

--------------------------------

### NativeFunctionCallStreamParser Example

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/api-reference/tool-emulation.md

Parses tool calls formatted for the Native Bridge from a stream. Execute native tools directly using the extracted call information.

```javascript
const parser = new NativeFunctionCallStreamParser();

for await (const chunk of streamResponse) {
  const { calls, text } = parser.processDelta(chunk);
  
  calls.forEach(call => {
    executeNativeTool(call.name, call.args);
  });
}
```

--------------------------------

### WindsurfAPI Project File Structure

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/MANIFEST.md

This tree outlines the organization of the generated documentation files for the WindsurfAPI project, including core documents, API references, and auxiliary files.

```tree
output/
├── README.md                    # 文档导航和快速入门
├── MANIFEST.md                  # 本文件 - 统计和清单
├── architecture.md              # 系统架构详解
├── configuration.md             # 环境变量和配置
├── types.md                     # 类型定义
├── errors.md                    # 错误代码和处理
│
└── api-reference/
    ├── http-endpoints.md        # HTTP API 参考
    ├── account-pool.md          # 账号池 API
    ├── models.md                # 模型目录 API
    ├── windsurf-client.md       # gRPC 客户端 API
    └── tool-emulation.md        # 工具系统 API
```

--------------------------------

### WindsurfAPI High-Level Architecture Diagram

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/architecture.md

This diagram illustrates the layered architecture of WindsurfAPI, from the HTTP service and routing to the gRPC client and external services like the Language Server and Windsurf Cascade. It shows the flow of requests and the responsibilities of each component.

```text
┌────────────────────────────────────────────────────────────────┐
│                    HTTP 服务 (Node.js)                          │
│                      端口 3003                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │             路由层 (src/server.js)                       │    │
│  │  /v1/chat/completions → handleChatCompletions           │    │
│  │  /v1/messages → handleMessages                           │    │
│  │  /auth/login → 账号管理                                  │    │
│  │  /dashboard → 管理 UI                                   │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              ↓                                    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │         处理程序层 (src/handlers/)                        │    │
│  │  • chat.js - OpenAI 处理                                 │    │
│  │  • messages.js - Anthropic 处理                         │    │
│  │  • tool-emulation.js - 工具调用                         │    │
│  │  • models.js - 模型列表                                 │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              ↓                                    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │         业务逻辑层                                        │    │
│  │  • auth.js - 账号池 + 轮询 + 速率限制                   │    │
│  │  • models.js - 模型目录 + 云端同步                      │    │
│  │  • conversation-pool.js - 对话复用                      │    │
│  │  • cache.js - 响应缓存                                  │    │
│  │  • runtime-config.js - 运行时实验配置                  │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              ↓                                    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │         gRPC 客户端层 (src/client.js)                   │    │
│  │  • WindsurfClient 主类                                  │    │
│  │  • 两条路由：Legacy (RawGetChatMessage) + Cascade      │    │
│  │  • 工具映射到 Cascade 内置工具                          │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              ↓                                    │
├─────────────────────────────────────────────────────────────────┤
│                   Language Server (gRPC HTTP/2)                   │
│            /opt/windsurf/language_server_linux_x64               │
│                      端口 42100 (默认)                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│              Windsurf Cascade (云端)                             │
│         server.self-serve.windsurf.com (HTTPS)                  │
│                                                                   │
└────────────────────────────────────────────────────────────────┘
```

--------------------------------

### Anthropic Format Authentication Error

Source: https://github.com/dwgx/windsurfapi/blob/master/_autodocs/errors.md

Example of an authentication error in Anthropic's JSON format. This indicates an issue with API key validation or account status.

```json
{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "No active accounts"
  }
}
```

--------------------------------

### Run Shard and Release Workflow Tests

Source: https://github.com/dwgx/windsurfapi/blob/master/docs/releases/RELEASE_NOTES_2.0.138.md

Execute specific shard and release workflow tests using Node.js.

```bash
node --test test/test-shard-script.test.js test/release-workflow.test.js
```