webpage-review API

Every route below sits under one base address.

https://public-tools.hjc925.cloud/webpage-review

The client holds one base address and builds every route from it. Nothing in this system may assume that it is mounted at the root of a host. Asset paths, redirects and the cookie path are all built from the configured prefix.

Two authentication models

The tool has two groups of routes. They do not share an authentication method.

Route group	Credential	Held by
`/api/*`	`Authorization: Bearer <token>`	The Chrome extension
`/admin/api/*`	Gateway session cookie	Herman’s browser

POST /webpage-review/api/threads HTTP/1.1
Host: public-tools.hjc925.cloud
Authorization: Bearer <reviewer-token>
Content-Type: application/json

The cookie is httpOnly, Secure and SameSite=Lax. Its Path is set explicitly.

Status codes

The codes carry meaning. A client must treat them differently.

Code	Meaning	What the client should do
`401`	No token, or an unknown token	Ask for a token
`403`	The token is valid, the role is too low	Do not retry
`410`	The session is revoked or expired	Stop. Ask Herman for a new token
`413`	The upload is larger than the limit	Show the effective limit
`429`	More than 60 writes in one minute	Wait for `Retry-After`

401 and 410 are separate answers on purpose. A client that treats them as one either retries a dead session forever or throws away a good token.

Reviewer routes

These routes use the bearer token.

Session

Method	Path	Purpose
`POST`	`/api/auth`	Exchange a token, return the session
`GET`	`/api/auth` or `/api/session`	Read the current session
`POST`	`/api/session/name`	Set the display name, one time only
`GET`	`/api/sites`	The whitelist for this project

A session response carries the session, the project, the author, the whitelist, the anchor algorithm versions and the upload limits.

{
  "session": { "id": "...", "label": "...", "role": "reviewer", "expiresAt": "...", "displayName": "Emma" },
  "project": { "id": "...", "name": "..." },
  "canSetDisplayName": false,
  "sites": ["https://example.com/docs"],
  "algoVersion": 2,
  "uploads": { "maxFileBytes": 67108864, "maxFilesPerComment": 5, "quotaBytes": 0, "usedBytes": 0 }
}

canSetDisplayName is sent as a fact. The client does not infer it from displayName being empty. This way the prompt appears exactly once and no control is drawn that would fail.

Threads and comments

Method	Path	Purpose
`GET`	`/api/threads`	List threads
`POST`	`/api/threads`	Create a thread
`DELETE`	`/api/threads/{id}`	Delete a thread
`POST`	`/api/threads/{id}/comments`	Add a comment
`POST`	`/api/threads/{id}/resolve`	Mark resolved
`POST`	`/api/threads/{id}/reopen`	Mark open
`POST`	`/api/threads/{id}/repin`	Move the anchor
`POST`	`/api/threads/{id}/orphan`	Mark the anchor as lost
`POST`	`/api/threads/{id}/seen`	Mark one thread as read
`GET`	`/api/unread`	Unread counts
`POST`	`/api/seen`	Mark several threads as read

Uploads

Method	Path	Purpose
`POST`	`/api/comments/{id}/uploads`	Attach a file to a comment
`GET`	`/api/uploads/{id}`	Fetch a file
`DELETE`	`/api/uploads/{id}`	Remove a file

Admin routes

These routes use the gateway session cookie. The account also needs the webpage-review flag.

Projects

Method	Path	Purpose
`GET`	`/admin/api/projects`	List projects
`POST`	`/admin/api/projects`	Create a project
`PATCH`	`/admin/api/projects/{id}`	Rename a project
`POST`	`/admin/api/projects/{id}/delete`	Delete a project

Whitelist

Method	Path	Purpose
`GET`	`/admin/api/projects/{id}/whitelist`	List the addresses
`POST`	`/admin/api/projects/{id}/whitelist`	Add an address
`DELETE`	`/admin/api/whitelist/{id}`	Remove an address

Reviewer sessions

Method	Path	Purpose
`GET`	`/admin/api/projects/{id}/sessions`	List the tokens
`POST`	`/admin/api/projects/{id}/sessions`	Mint a token
`POST`	`/admin/api/sessions/{id}/revoke`	Revoke a token
`POST`	`/admin/api/sessions/{id}/reissue`	Replace a token
`POST`	`/admin/api/sessions/{id}/extend`	Extend the expiry date
`DELETE`	`/admin/api/sessions/{id}`	Delete a token

A token lasts 7, 14, 30 or 90 days. The default is 30 days.

The validity is a closed set, not a range. A typed “90000 days” cannot quietly mint a permanent credential.

Threads, uploads and read state

Method	Path	Purpose
`GET`	`/admin/api/threads`	Every thread across projects
`GET`	`/admin/api/projects/{id}/threads`	Threads for one project
`POST`	`/admin/api/threads/{id}/comments`	Reply as the admin
`POST`	`/admin/api/threads/{id}/resolve`	Mark resolved
`POST`	`/admin/api/threads/{id}/reopen`	Mark open
`POST`	`/admin/api/threads/{id}/seen`	Mark one thread as read
`DELETE`	`/admin/api/threads/{id}`	Delete a thread
`GET`	`/admin/api/uploads/{id}`	Fetch a file
`DELETE`	`/admin/api/uploads/{id}`	Remove a file
`GET`	`/admin/api/unread`	Unread counts
`POST`	`/admin/api/seen`	Mark several threads as read

Identifiers

Every {id} matches this pattern.

[A-Za-z0-9_-]{1,64}

Sizes

The system uses 1024 × 1024 for one megabyte, everywhere. The conversion from a typed megabyte figure to bytes happens one time, in the router.

The two readings of a megabyte differ by 4.9 percent at 1000 MB. Nobody would notice which one shipped. For that reason the choice is made in one place and written down.

Start here

LLM gateway

Public tools

Hermes

Two authentication models

Status codes

Reviewer routes

Session

Threads and comments

Uploads

Admin routes

Projects

Whitelist

Reviewer sessions

Threads, uploads and read state

Identifiers

Sizes

​Two authentication models

​Status codes

​Reviewer routes

​Session

​Threads and comments

​Uploads

​Admin routes

​Projects

​Whitelist

​Reviewer sessions

​Threads, uploads and read state

​Identifiers

​Sizes

Two authentication models

Status codes

Reviewer routes

Session

Threads and comments

Uploads

Admin routes

Projects

Whitelist

Reviewer sessions

Threads, uploads and read state

Identifiers

Sizes