Docs/API

win.sh API reference

Public API documentation for local loop harnesses, browser-approved tokens, bearer auth, and hosted connector snapshots.

Overview

The current API is intentionally small. Hosted win.sh gives local loop harnesses a safe way to authenticate and read connector snapshots before an agent run.

Base URL: https://win.sh
Public API prefix: /v1
Token prefix: win_live_
Response format: application/json

Token management lives under /api/settings because it is a web-app settings surface. Local harnesses should use /v1 for machine-to-machine reads.

Authentication

Send API tokens with standard bearer auth. Tokens are shown once at creation time and only their hashes are stored.

Authorization: Bearer win_live_...

The first supported API scope is snapshots:read. The token model also stores loops:read and loops:run for the local harness contract, but hosted write endpoints are not public yet.

CLI approval flow

The local CLI starts a localhost callback, opens win.sh, and waits for the browser approval redirect. This lets users connect the terminal without pasting a token by hand.

win auth login

GET /settings/api-tokens/cli?client=win-loops
  &redirect_uri=http://127.0.0.1:49152/callback
  &state=<random-state>

After approval, win.sh redirects to the local callback with token, state, workspace, api_url, and expires_at.

http://127.0.0.1:49152/callback
  ?token=win_live_...
  &state=<same-random-state>
  &workspace=<workspace-id>
  &api_url=https%3A%2F%2Fwin.sh
  &expires_at=2026-09-14T18%3A00%3A00.000Z

The approval page only accepts local HTTP callbacks on 127.0.0.1, localhost, or ::1. The CLI must verify that the returned state matches the value it generated.

Token endpoints

These endpoints require a signed-in browser session. API bearer tokens cannot create, list, or revoke other API tokens.

GET/api/settings/api-tokens

List the current user's tokens. Revoked tokens are included for auditability.

{
  "tokens": [
    {
      "_id": "65f...",
      "name": "Local CLI",
      "tokenPrefix": "win_live_abc",
      "lastFour": "9xYz",
      "scopes": ["loops:read", "loops:run", "snapshots:read"],
      "source": "cli",
      "client": "win-loops",
      "createdAt": "2026-06-16T18:00:00.000Z",
      "lastUsedAt": null,
      "expiresAt": "2026-09-14T18:00:00.000Z",
      "revokedAt": null
    }
  ]
}

POST/api/settings/api-tokens

Create a token. The raw token is returned once in the response body.

{
  "name": "Local CLI",
  "source": "settings",
  "client": "win-loops",
  "scopes": ["loops:read", "loops:run", "snapshots:read"],
  "expiresInDays": 90
}

expiresInDays defaults to 90 and is bounded from 1 to 365 days. Pass "expiresAt": null only when a non-expiring token is intentional.

{
  "token": "win_live_...",
  "apiToken": {
    "_id": "65f...",
    "name": "Local CLI",
    "tokenPrefix": "win_live_abc",
    "lastFour": "9xYz",
    "scopes": ["loops:read", "loops:run", "snapshots:read"],
    "source": "settings",
    "client": "win-loops",
    "expiresAt": "2026-09-14T18:00:00.000Z",
    "revokedAt": null
  }
}

DELETE/api/settings/api-tokens/{id}

Revoke a token owned by the current user.

Connector snapshots

Local loops can request a hosted connector snapshot before handing work to Codex, Claude Code, or another agent runtime. This endpoint requires an API token with snapshots:read.

GET/v1/loops/{loop}/connector-snapshot

Return the latest connector snapshot available for a loop and workspace.

curl https://win.sh/v1/loops/bug-autofix/connector-snapshot \
  -H "Authorization: Bearer win_live_..."

{
  "apiVersion": "2026-06-16",
  "loopId": "bug-autofix",
  "generatedAt": "2026-06-16T18:00:00.000Z",
  "workspace": "workspace_123",
  "status": "empty",
  "connectors": [],
  "signals": [],
  "message": "No hosted connector snapshot is available for this workspace yet. Connect tools in win.sh, then fetch this endpoint again."
}

The placeholder response is deliberate. It gives the CLI a stable contract now, while hosted connector-specific snapshots are added behind the same endpoint.

Errors

Errors use standard HTTP status codes and a compact JSON body.

401: Missing, invalid, expired, or revoked authentication.
403: The current auth method or token scope cannot access the endpoint.
404: The requested resource does not exist or does not belong to the user.

{
  "statusCode": 403,
  "message": "Missing required scope: snapshots:read"
}

Security notes

Only token hashes are stored server-side.
Existing tokens can be revoked, but raw token values cannot be retrieved.
Token management requires a signed-in browser session, not API-token auth.
The CLI approval route only accepts local HTTP callbacks.
Local CLIs must verify the returned OAuth-style state before storing a token.
Use short-lived, scoped tokens for local harnesses and CI.