WindsurfAPI Documentation

WindsurfAPI converts Windsurf/Devin AI models (including Claude, GPT, Gemini, DeepSeek, etc.) into three standard API formats:

• OpenAI Compatible: POST /v1/chat/completions (compatible with any OpenAI SDK).
• OpenAI Responses Compatible: POST /v1/responses (includes GET and DELETE /v1/responses/{id} for managing stored responses).
• Anthropic Compatible: POST /v1/messages (compatible with Claude Code, Cline, and Cursor).
• Gemini Compatible: POST /v1beta/models/* (compatible with Gemini SDK).

The service acts as a proxy that translates HTTP requests into Windsurf's internal gRPC protocol via a local Language Server (LS), manages an account pool with automatic rotation, rate limiting, and failover, and masks the upstream identity to present the models as their original providers (e.g., claiming to be Claude Opus 4.6).

The Audit Ledger tracks which subsystems have been exhaustively scanned for defects. It uses the following status indicators to communicate security and stability posture:

• ✅ CLEAN: The module was probed (e.g., via fuzzing) and no defects were found. Includes details on the probing method.
• 🛡 GUARDED: Critical invariants are protected by tests that have undergone mutation testing (verifying that injecting regressions causes tests to fail).
• ⚠️ FINDINGS: Defects were discovered and subsequently fixed; associated commits are listed.
• ⬜ UNAUDITED: The module has not yet undergone an exhaustive scan.

Note on Mutation Testing: A test that has never failed during mutation is considered unreliable. 🛡 status indicates that historical defects or regressions were re-injected to confirm the guards fail as expected.

If you prefer a development workflow or want to use git pull for updates, use the source-based method. This requires Node.js 20+ installed.

Setup Steps:

1. Initial Setup: Double-click start.bat. This script validates Node.js, generates a .env file with random API_KEY and DASHBOARD_PASSWORD, and prints the credentials and dashboard URL to the console.
2. Access Dashboard: Open http://127.0.0.1:3003/dashboard in your browser and use the printed DASHBOARD_PASSWORD to log in.
3. Add Sessions: Navigate to the accounts page in the dashboard to add a Windsurf/Devin session token.
4. Background/Auto-start: To run as a persistent background service that starts on boot, run install-task.bat to register a Windows Scheduled Task.

Use the DEVIN_CONNECT_DEBUG_META=1 flag during a normal request to dump every varint subfield of the #7 metadata sub-message to the logs. This is the primary method for discovering the integer tags required for billing, caching, and tool-calling configuration.

DEVIN_CONNECT_DEBUG_META=1 <your normal request>

To run the WindsurfAPI using PM2, install PM2 globally and start the entry point. Note: Do not use pm2 restart to avoid zombie processes; instead, use the provided update.sh script for updates.

npm install -g pm2
pm2 start src/index.js --name windsurf-api
pm2 save && pm2 startup

To use the Devin cloud GetChatMessage route via pure HTTP (which is required for environments like homecloud that lack the devin CLI or language_server binary), set the DEVIN_CONNECT=1 environment variable.

Important: Do not use DEVIN_ONLY=1 on homecloud, as it attempts to run a local devin subprocess and will result in 503 errors for every request.

# Minimal .env configuration for homecloud
DEVIN_CONNECT=1
API_KEY=sk-REDACTED

To add a new account to the pool, use the login:devin command. This command logs in, encrypts and stores the credentials for auto-relogin, adds the account to the pool, and verifies the account tier. Running without flags performs an offline self-test.

DEVIN_CONNECT_CRED_KEY=<key> LOGIN_REAL=1 LOGIN_EMAIL=<e> LOGIN_PASSWORD=<p> npm run login:devin

To deploy WindsurfAPI quickly on a local machine, clone the repository, run the setup script to configure permissions and environment variables, and start the Node.js server.

Dashboard access: http://<YOUR_IP>:3003/dashboard

git clone https://github.com/dwgx/WindsurfAPI.git
cd WindsurfAPI
bash setup.sh          # Creates directories, configures permissions, generates .env
node src/index.js

Cursor's client-side whitelist may intercept model names containing claude. To bypass this, use the following aliases in the Cursor model configuration field:

Note: GPT, Gemini, and DeepSeek models are not restricted by the Cursor whitelist and can use their original names.

To enable vision capabilities, you must discover the protobuf tag for the nested images field. This requires a paid token with vision entitlements. The tool probes candidate tags against a vision model and writes the result to devin-connect-image-tag.json.

IMAGE_CALIBRATE_REAL=1 CONNECT_SMOKE_TOKEN=<paid-vision-token> \
  IMAGE_CALIBRATE_MODEL=claude-opus-4.8 npm run calibrate:devin-image

The backend should return machine-readable error codes (prefixed with ERR_) instead of raw localized strings. The frontend then maps these codes to translations.

Backend Response:

res.json({ error: 'ERR_INVALID_CREDENTIALS' });

Locale JSON:

// en.json
{ "error": { "ERR_INVALID_CREDENTIALS": "Invalid email or password" } }

// Before
res.json({ error: '邮箱或密码错误' });

// After
res.json({ error: 'ERR_INVALID_CREDENTIALS' });