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>

Web dashboard — GitHub OAuth (cookie session)

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).

See also: Cloud settings sync →, Team Tracker →, Scalar API reference →.