Build your own client

Use the wrangl-server HTTP API and its OpenAPI spec to write scripts, integrations, or your own interface.

wrangl-server serves the Wrangl app, and the app talks to the server through a plain HTTP and WebSocket API. You can use the same API from a script, a native app, or your own web interface. The HTTP part is described in an OpenAPI 3.1 file that the Wrangl repository generates from the server's own code.

The API is not versioned yet. Routes and fields can change between releases. Read the spec that matches the server version you run.

Send your first request

The examples use http://127.0.0.1:8080. Replace it with your server's address.

/health needs no token:

curl http://127.0.0.1:8080/health

{"status":"ok","allowRemoteWrites":true,"caseInsensitivePaths":false,"setupRequired":false}

Every other API route needs the access token when the server has one. Send it in the Authorization header:

TOKEN=$(cat ~/.local/state/wrangl/web-auth-token)  # the default location
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/projects

{"success":true,"data":{"projects":[{"id":"439bcfbd-…","name":"wrangl","color":"yellow","path":"/home/me/wrangl","isArchived":false,"isDefault":true}],"defaultProjectId":"439bcfbd-…"}}

The server accepts the token only in the header. A ?token= query parameter does not work. To find or set the token, see The access token.

Get the spec

A running server serves the spec for its own version at /openapi.json. A server that still shows its setup page does not. That route needs the token, like the other API routes:

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/openapi.json

You can also get the spec without a running server:

Download openapi.yaml from the latest release. Each stable and nightly release has its own copy.
Run wrangl-server openapi to print the spec of the binary you have. Add --format json for JSON.
Browse the spec in the interactive API reference. It shows the latest stable release that ships the spec, as of the last docs deploy.

Import the spec into Postman, Insomnia, Bruno, or a code generator such as openapi-generator to get a typed client.

The spec covers the HTTP routes. The WebSocket message protocol is described separately. See Use the WebSockets.

Read the response envelope

Most JSON routes wrap their result in the same envelope:

Field	Type	Meaning
`success`	boolean	`true` when the request worked.
`data`	any	The result. Present when `success` is `true`.
`error`	string	A message for people. Present when `success` is `false`.
`code`	string	A stable error code, such as `UNAUTHORIZED`, `FORBIDDEN`, or `OUTSIDE_PROJECT_ROOT`. Check this field in code, not `error`.

A missing or wrong token returns HTTP 401 with {"success":false,"error":"Unauthorized","code":"UNAUTHORIZED"}. Other failures can return HTTP 200 with success: false, so always check success.

Know what a client can change

A client on the same machine as the server can make changes. A client on another device is view-only, unless the server runs with --allow-remote-writes. Routes that change files, git, projects, or settings return FORBIDDEN to a view-only client. GET /health tells the calling client whether it may make changes, in allowRemoteWrites. A client on the same machine always gets true. See Allow changes from other devices.

Routes that work on a path, such as /git/* and /worktree/*, accept only paths inside a registered project. Register a folder first with POST /projects.

Call it from a web page

The server does not send CORS headers. A browser therefore blocks a page on another origin, such as http://localhost:3000, from calling the API. Scripts, servers, and native apps are not affected, because the browser is the one that enforces CORS.

To run your own web interface against wrangl-server, serve it from the same origin as the server. One way is a reverse proxy that sends / to your interface and the API paths to wrangl-server. If the proxy changes the host name, list the public address with --allowed-origins. See Put a reverse proxy in front.

Use the WebSockets

Chats, agents, and terminals run over two WebSocket endpoints:

/ws carries chat sessions, prompts, approvals, and live events.
/terminal/ws carries terminal input and output.

The upgrade request itself needs no token. After the socket opens, send an authenticate request first. Put the token in its payload:

{"id":"1","type":"authenticate","payload":{"protocolVersion":7,"deviceId":"my-client","clientInstanceId":"my-client-1","token":"<token>"}}

The server refuses an authenticate with a different protocolVersion. The current frames, request types, and version number are in src/shared/types/web-protocol.types.ts in the Wrangl repository. The Wrangl web app is the reference client, and its socket code is in src/renderer/lib/.

Add a route to the spec

This section is for people who change the Wrangl server. The server builds the spec from its own Rust types, so no spec file is checked in and there is nothing to regenerate. When you add or remove an HTTP route, add or remove its row in the ROUTES table in src-tauri/src/web/openapi/. A Rust test fails until the table and the router match.