wflows
Sign inGet wflow

on wflows.io

v0 API reference

Read-only catalog endpoints are open. Authenticated endpoints (your account, favorites, publish) require a Bearer token issued by the desktop sign-in handshake.

Auth

Tokens are minted via the desktop sign-in flow. Open https://wflows.io/auth/desktop?nonce=<random> in the user's browser. After they sign in, the page redirects to wflow://auth/callback?nonce=...&token=... (deeplink), and falls back to the polling exchange endpoint below.

Once you have a token, send it as Authorization: Bearer wfd_... on authenticated calls. 401 means revoked — drop the token and re-run the sign-in handshake.

Read-only catalog

GET /api/v0/featured

Featured workflows for the homepage grid. Up to 6 entries. Public, no auth.

curl https://wflows.io/api/v0/featured

GET /api/v0/browse

The full library, paginated. Supports query params:q (full-text search), tag (filter by tag slug), trigger (chord / hotstring / on-demand), sort (recent / popular), offset.

curl 'https://wflows.io/api/v0/browse?q=focus&sort=popular'

GET /api/v0/workflow/[handle]/[slug]

Full workflow detail including the KDL source, readme, step trail, and author info.

curl https://wflows.io/api/v0/workflow/cush/focus-mode

Authenticated

POST /api/v0/auth/desktop/exchange

Polling fallback for the desktop sign-in handshake. Body: {"nonce": "..."}. Returns {"token": "wfd_...", "user": { handle, displayName, avatar }} once on first call (after the user signs in), 404 thereafter.

GET /api/v0/me

The authenticated user's profile.

curl -H "Authorization: Bearer wfd_..." \
  https://wflows.io/api/v0/me

Returns { handle, displayName, avatar, tier, isFounding, createdAt }.

GET /api/v0/favorites

The authenticated user's installed workflows. Same envelope as /api/v0/browse so the desktop can reuse its renderer.

POST /api/v0/workflows

Publish a workflow on behalf of the authenticated user. Body:

{
  "kdl": "workflow \"...\" { ... }",
  "description": "optional one-liner",
  "readme": "optional markdown",
  "tags": ["focus", "shell"],
  "visibility": "public" | "draft"
}

Returns { workflowId, handle, slug, url } on 201, or a 400 with { error, message, errors? } on validation failure (parser errors land in the errors array).

CORS

v0 endpoints ship with Access-Control-Allow-Origin: * for the catalog endpoints since they expose only public data, plus Authorization on the allowed headers list. Preflight is cached for 5 minutes.

Rate limits

Vercel's per-function instance limits gate the endpoints today. No explicit per-IP rate limit yet. If you're hitting limits, ping hello@wflows.io.

Versioning

These endpoints are /api/v0/... deliberately. v0 = catalog read-only + desktop sign-in + publish. v1 will add comments, runs (paid tier), and cloud sync (paid tier). v1 endpoints will live under /api/v1/...; v0 stays stable for the desktop's lifetime.

Next

wflow:// protocol →