API reference

Everything the admin panel and the Android app do, they do through this API — so anything they can do, your code can do.

OverviewBase URL, auth, errors, rate limits and CORS.

AuthenticationRegister, sign in, verify, reset, Google.

WatchesCRUD, run now, run all.

Runs and feedbackHistory, labels, accuracy and collection stats.

AI assistanceDraft, revise, explain, preview, liveness.

Trust registryYour domain-to-tier rules.

DevicesPush token registration.

Admin: keys and modelsKey pools and per-category model config.

Every route at a glance

Method	Path	Auth	Purpose
GET	/health	Public	Liveness probe. Returns { "status": "ok" }.
GET	/config/status	Public	Which integrations are configured, as booleans. Never returns a value.
POST	/auth/register	Public	Create an account (role user) and return a token.
POST	/auth/login	Public	Exchange email and password for a token.
POST	/auth/google	Public	Exchange a Google ID token for a session. 503 when Google sign-in is not configured.
GET	/auth/me	Token	The current user.
POST	/auth/verify-email	Public	Confirm an emailed verification link.
POST	/auth/request-verification	Token	Resend the verification email. Always 200.
POST	/auth/forgot-password	Public	Start a password reset. Always 200, so it cannot probe which emails exist.
POST	/auth/reset-password	Public	Complete a reset with the emailed token and a new password.
GET	/watches	Token	List the caller's watches.
POST	/watches	Token	Create a watch. The owner is taken from your token, never the body.
GET	/watches/:id	Token	Fetch one owned watch.
PUT	/watches/:id	Token	Replace one owned watch. Id and owner are not client-settable.
DELETE	/watches/:id	Token	Delete one owned watch. Run history is kept.
GET	/watches/:id/runs	Token	Run history, newest first. Accepts ?limit=.
POST	/watches/:id/run	Token	Run this watch now, ignoring its schedule. Returns the outcome.
POST	/watches/run-all	Token	Run all of the caller's enabled watches now. 409 if one is already in flight.
POST	/watches/draft	Token	Turn a plain-English description into a draft watch. Nothing is saved.
POST	/watches/draft/check-domains	Token	Best-effort liveness check for suggested domains.
POST	/watches/draft/preview	Token	Dry-run a search source and return the top candidate titles and URLs.
POST	/watches/:id/explain	Token	Explain an existing watch in plain English. Read-only.
POST	/watches/:id/revise	Token	Propose a field-level change set from one instruction. Nothing is saved.
POST	/runs/:id/feedback	Token	Label a run correct or wrong, or clear the label with null.
GET	/feedback/stats	Token	Rolling precision, recall and F1 with recent false positives and negatives.
GET	/collection/stats	Token	Rolling collection metrics, including the extraction rate.
GET	/trust-registry	Token	The caller's domain-to-tier rules.
PUT	/trust-registry/:domain	Token	Upsert a trust rule. The domain is lowercased.
DELETE	/trust-registry/:domain	Token	Delete a trust rule.
PUT	/devices/:token	Token	Register or refresh a push token for the caller.
DELETE	/devices/:token	Token	Unregister a push token.
GET	/admin/keys	Admin role	Key pools per use-case category, with masked previews and live status.
POST	/admin/keys	Admin role	Add a key. It is probed live and only stored if the probe succeeds.
DELETE	/admin/keys/:id	Admin role	Remove a stored key.
GET	/admin/keys/:id/metrics	Admin role	Daily usage series for one key. Accepts ?days=.
POST	/admin/keys/:id/validate	Admin role	Re-probe a key on demand. Success revives a key marked dead.
PUT	/admin/categories/:category	Admin role	Set the provider and model for one use-case category.