API Routes¶

All routes are served by the Cloudflare Worker.

Webhook receiver¶

POST /api/webhook

Receives GitHub App webhook events. The payload is verified using the WEBHOOK_SECRET HMAC signature before processing.

Handled events:

Event	Action	Behavior
`issues`	`opened`	Resolve template, post managed comment
`issues`	`type_changed`	Re-resolve template, merge state, update comment
`issues`	`transferred`	Re-resolve from new repo context, merge state, update comment
`issue_comment`	`created`	Ignored (non-bot comments are no-ops)

Badge endpoint¶

GET /api/badge/:owner/:repo/:issue

Returns a dynamic SVG badge for the given issue's checklist state.

Parameters:

Parameter	Type	Description
`owner`	string	GitHub org or user name
`repo`	string	Repository name
`issue`	number	Issue number

Response: image/svg+xml with Cache-Control: s-maxage=60

State update¶

PATCH /api/state/:owner/:repo/:issue

Updates one or more checklist items. Requires an active GitHub OAuth session (collaborator verified).

Request body:

{
  "items": [
    { "id": "s1", "status": "done" },
    { "id": "s2", "status": "exception", "approvedBy": "alice" }
  ]
}

Validation: - Session must be authenticated via GitHub OAuth - User must have write access to the repo - For exception items: approver must satisfy the exception approval rules

Response: 200 OK with the updated full state, or 4xx with an error message.

GitHub OAuth¶

GET /auth/github

Redirects the user to GitHub's OAuth authorization page.

GET /auth/callback

GitHub redirects here after authorization. The app exchanges the code for a token, verifies collaborator access, and sets a session cookie.

Checklist UI¶

GET /checklist/:owner/:repo/:issue

Serves the checklist editor. Requires an authenticated session; unauthenticated requests are redirected to /auth/github.