Docs/API reference

win.sh API reference

Browser-approved API tokens, local CLI authentication, and hosted connector snapshots for the open-source loop harness.

Terminal

npm install -g @win.sh/win
win auth login
win snapshot fetch bug-autofix

Base URL: https://win.sh
API prefix: /v1
Token prefix: win_live_
Format: application/json

Core concepts

Small API, stable local contract

The public API exists to connect local loop harnesses to hosted win.sh. The hosted app stores connector credentials, creates scoped tokens, and returns business snapshots that local agents can safely use during a run.

Machine endpoints use /v1.

Settings endpoints use /api/settings because they require a signed-in browser session.

Authentication

Use bearer tokens for machine requests

API tokens are shown once at creation time. win.sh stores token hashes, tracks usage metadata, and rejects expired or revoked tokens.

AuthorizationHeader

Send Bearer win_live_... with every machine request.

snapshots:readScope

Required for hosted connector snapshot reads.

loops:read / loops:runReserved scopes

Stored for local harness contracts. Hosted write endpoints are not public yet.

Browser approval

Connect the terminal without pasting tokens

The CLI starts a localhost callback, opens the approval page, and waits for a browser redirect. The CLI must verify the returned state before storing the token.

GET/settings/api-tokens/cli

Open a signed-in browser approval flow for a local CLI token.

clientstring

Human-readable client name, usually win-loops.

redirect_uriURL

Local HTTP callback on 127.0.0.1, localhost, or ::1.

statestring

Random value generated by the CLI and checked after redirect.

RequestURL

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

RedirectURL

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

Token management

Create, list, and revoke API tokens

Token management 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.

POST/api/settings/api-tokens

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

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

Revoke a token owned by the current user.

namestring

Display name shown in Settings.

scopesstring[]

Allowed values include loops:read, loops:run, and snapshots:read.

expiresInDaysnumber

Defaults to 90 and is bounded from 1 to 365 days.

Create tokenJSON

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

ResponseJSON

{
  "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
  }
}

List tokensJSON

{
  "tokens": [
    {
      "_id": "65f...",
      "name": "Local CLI",
      "tokenPrefix": "win_live_abc",
      "lastFour": "9xYz",
      "lastUsedAt": null,
      "revokedAt": null
    }
  ]
}

Connector snapshots

Fetch hosted business signals before a local run

Local loops can request a hosted connector snapshot before handing work to Codex, Claude Code, or another 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.

loopPath parameter

Loop id such as bug-autofix, seo-growth, or feedback-to-fix.

AuthorizationHeader

Bearer token with snapshots:read.

Requestbash

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

ResponseJSON

{
  "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."
}

Errors

Standard HTTP status codes

Errors use standard HTTP status codes and a compact JSON response. Treat 401 as an auth refresh problem and 403 as a scope or permission problem.

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.

Security

Token handling rules

Only token hashes are stored server-side.
Raw token values are shown once and cannot be retrieved later.
Token management requires a signed-in browser session.
The CLI approval route only accepts local HTTP callbacks.
Local CLIs must verify the returned OAuth-style state.
Use short-lived, scoped tokens for local harnesses and CI.