Cloud API

SnakeFlow Cloud is served by the snakeflow-api Cloudflare Worker (api/ in the monorepo). All routes live under /api.

Base URLs

Client	URL	Notes
VS Code / Cursor extension	`devManager.cloud.apiUrl` (default `https://snakeflow-api.pro-connect.workers.dev`)	Direct Worker URL; sends `Authorization: Bearer <JWT>`.
Web dashboard (Pages)	`https://snakeflow-cloud.pages.dev/api/*`	Proxied to the Worker; browser uses HttpOnly `sf_token` cookie.
Docs site (Scalar UI)	snakeflow.pages.dev/api-reference/	Interactive OpenAPI browser (core sync endpoints only).

The extension and dashboard hit the same route handlers; only transport (header vs cookie) differs.

Authentication

Extension / CI — JWT via GitHub token

POST /api/auth/verify
Content-Type: application/json

{ "github_token": "<GitHub PAT or OAuth token>" }

Response 200: { "token": "<JWT>", "login": "...", "avatar_url": "..." } — JWT valid 30 days (HS256).

Send on protected calls:

Authorization: Bearer <token>

Method	Path	Description
`GET`	`/api/auth/github`	Redirect to GitHub OAuth (`read:user`). Sets CSRF `state` cookie.
`GET`	`/api/auth/callback`	OAuth callback; sets HttpOnly `sf_token` JWT cookie.
`POST`	`/api/auth/logout`	Clears session cookies. `{ "ok": true }`

Callback URLs use SITE_URL (dashboard origin) when set.

Settings access model

Repository settings are gated by workspace membership (there is no /permissions endpoint):

A repo must match at least one workspace repo pattern (owner/*, exact owner/repo, etc.).
Admin of a matching workspace → push, pull, delete settings.
Member of a matching workspace → pull only.
First push to a personal repo (owner === your GitHub login) with no workspace → API auto-creates a personal workspace {login} with pattern {login}/*.
Org repos with no matching workspace → 409 workspace_required with a suggested pattern.

X-GitHub-Token is required for PUT /api/settings/:owner/:repo (GitHub repo access check). It is not stored on the server. GET and DELETE use JWT + workspace role only.

Main routes (`/api/*`)

Method	Path	Auth	Description
`POST`	`/auth/verify`	—	Exchange GitHub token for JWT.
`GET`	`/me`	JWT	Profile: `id`, `login`, `plan`, `status`. Effective plan is `pro` while billing is dormant.
`GET`	`/projects`	JWT	Repositories visible via workspace patterns.
`GET`	`/settings/:owner/:repo`	JWT	Pull settings snapshot. `404` if never synced.
`PUT`	`/settings/:owner/:repo`	JWT + `X-GitHub-Token`	Push `{ "settings": { "devManager.*": … } }`.
`DELETE`	`/settings/:owner/:repo`	JWT	Remove synced row for repo.
`POST`	`/billing/checkout`	JWT	Paddle checkout URL (billing dormant).
`POST`	`/billing/portal`	JWT	Paddle subscription management URL.
`POST`	`/paddle/webhook`	Paddle signature	Subscription lifecycle (server-to-server).
`GET`	`/claude-models?apiKey=`	JWT	Proxy Anthropic model list (caller-supplied key).
`GET`	`/gemini-models?apiKey=`	JWT	Proxy Google Gemini model list (caller-supplied key).
`POST`	`/events`	JWT	Activation funnel event `{ "event", "source" }`.
`GET`	`/admin/funnel`	Admin key	Activation metrics (`?key=` or `X-Snakeflow-Admin-Key`).

Team routes (`/api/team/*`)

All team routes require JWT. POST /workspaces/join skips the Pro gate; other routes pass through requirePro (currently always allowed while billing is dormant).

Profile & activity

Method	Path	Role	Description
`GET`	`/me`	any	Workspaces for caller.
`GET`	`/dashboard?workspace=&from=&to=`	admin	Team dashboard aggregates. Dates `YYYY-MM-DD`.
`GET`	`/active-minutes?day=`	member	Internal minutes per workspace for a UTC day.
`POST`	`/active-minutes`	member	Flush `{ "entries": [...], "timezone"?: "IANA" }`. Max 200 entries.
`POST`	`/commits`	admin	Daily commit counts by member/repo.
`POST`	`/closed-issues`	admin	Daily closed-issue counts by member/repo.
`GET`	`/effective-config?repo=owner/repo`	member	Merged workspace + project overrides for plugin auto-pull.

Workspaces

Method	Path	Role	Description
`POST`	`/workspaces/create`	Pro gate	Create workspace + initial invite.
`POST`	`/workspaces/join`	JWT	Join via invite code.
`DELETE`	`/workspaces/:id`	admin	Delete workspace and related data.
`GET`	`/workspaces/:id/members`	member	Member list.
`DELETE`	`/workspaces/:id/members?login=`	admin	Remove member.
`PATCH`	`/workspaces/:id/members`	admin	Change member role.
`GET`	`/workspaces/:id/invites`	admin	Active invites.
`POST`	`/workspaces/:id/invites`	admin	Create invite.
`GET`	`/workspaces/:id/patterns`	member	List repo patterns.
`PUT`	`/workspaces/:id/patterns`	admin	Replace repo patterns.
`GET`	`/workspaces/:id/settings`	member	Workspace `idle_window_minutes` + settings blob.
`PATCH`	`/workspaces/:id/settings`	admin	Update idle window and/or merge settings keys.
`GET`	`/workspaces/:id/project-settings`	member	Per-repo overrides in workspace.
`PUT`	`/workspaces/:id/project-settings/:owner/:repo`	admin	Set project-level overrides.
`DELETE`	`/workspaces/:id/project-settings/:owner/:repo`	admin	Remove project override.

Limits (server-enforced)

Area	Limit
Repo patterns per workspace	50 patterns, 200 chars each
Workspace name	1–100 chars
Active-minutes flush	200 entries/request; 1440 min/day; 60 min/hour (heatmap)
Commit / closed-issue sync	500 members; 200 repos/member; count 0–10 000
Workspace settings JSON	256 KB max
`idle_window_minutes`	1–15 (server); client clamps effective idle to 5–10 min

CORS

/api/* allows known dashboard origins with credentials; other origins get *. Allowed headers: Authorization, Content-Type, X-GitHub-Token, Paddle-Signature.

Local development

cd api
cp .dev.vars.example .dev.vars
npm run dev

Deploy: npm run deploy (D1 migrations + wrangler deploy).