API Reference

This reference describes the first-party HTTP API used by GearBeacon 1.2.0's browser UI. It is an owner API for a private installation, not a hosted public API. Use the server source and browser client for complete field schemas when building a client, and check capabilities instead of assuming a newer feature exists on an older server.

Sessions, CSRF, and errors

In authenticated modes, only health endpoints and owner authentication bootstrap routes are available without an owner session. GET /api/auth/status reports setup/authentication state. POST /api/auth/setup takes { "setupToken": "...", "password": "..." }; POST /api/auth/login takes { "password": "..." }. Successful setup/login sets a session cookie and returns csrfToken and sessionExpiresAt.

Keep the cookie for subsequent requests and send X-CSRF-Token for state-changing authenticated calls. JSON requests use Content-Type: application/json. Host/origin checks apply independently of login. Protect cookies/tokens as credentials; do not embed a real password in command examples or public scripts.

Status	Typical meaning
400	Invalid fields, unsupported filter, or incompatible import
401	Missing/invalid owner session or rejected login
403	Invalid CSRF token or disallowed origin
404	Missing route/product/watch/collection
409	Conflicting membership/name/state or disabled/incomplete test channel
421	Disallowed request Host
428	Owner setup required
429	Authentication rate limit
502 / 503	Upstream operation failed / health not ready

Read the response's error message; status depends on the endpoint. Do not disable security checks to work around a client error.

Regions and product identities

Use ?region=us, ca, eu, or uk for regional endpoints and an enabled region. Treat a returned slug as an opaque identity; URL-encode it in path parameters. Exact variants also expose parentSlug, variantId, variantSlug, and sku. Use the returned url for the Store link rather than constructing one from the identity.

GET /api/products normally includes parent products and watched variants. includeVariants=1 includes all retained variants; watchOnly=1 restricts to watched products. Product details expose parent/variant choices. Existing parent identities remain supported.

Endpoint map

Health, owner access, and configuration

Method	Path	Purpose
GET	/healthz, /readyz	Liveness and all-region readiness
GET	/api/status, /api/health	Regional status and detailed health
GET	/api/auth/status	Authentication/bootstrap state and current session CSRF token
POST	/api/auth/setup, /api/auth/login, /api/auth/logout	Create owner, sign in, revoke current session
GET / DELETE	/api/auth/sessions, /api/auth/sessions/:id	List sessions / revoke a selected session
PUT	/api/auth/password	Change owner password
GET / PUT	/api/config	Read sanitized configuration / save supported settings
POST	/api/config/validate	Validate proposed configuration
POST	/api/onboarding/complete	Complete guided setup

Products, watches, and collections

Method	Path	Purpose
GET	/api/products, /api/products/:slug	Catalog and product details; details accept days=7, 30, or 90 (default 30)
GET	/api/watchlist	Watched products
POST	/api/watch/add	Atomically add/reuse a watch and optional collection membership
POST	/api/watch	Add/update a watch with an optional rule
DELETE	/api/watch/:slug	Remove the watch and its collection memberships
GET / PUT	/api/watch/:slug/rules	Read / update watch rules
POST	/api/watch/:slug/preview	Evaluate an unsaved rule without recording an event or sending
POST	/api/watch/bulk	slugs plus action: pause, resume, remove, purchased, or wanted; pause can include minutes
POST	/api/watch/import/preview, /api/watch/import	Resolve import content / add confirmed slugs
GET / POST	/api/collections	Read workspace/capabilities / create collection
PUT / DELETE	/api/collections/:id	Edit or archive / delete a project
PUT	/api/watch/:slug/collections	Assign a watch's collection memberships
PUT / DELETE / POST	/api/collections/:id/items/:slug	Update plan / remove membership / restore an absent membership
POST	/api/check	Manually check the selected Store

Activity and notifications

Method	Path	Purpose
GET	/api/events	Recent regional events
GET	/api/activity, /api/activity/:id	Paginated confirmed events / event evidence and delivery outcomes
GET	/api/activity/export	Filtered CSV or JSON export
GET / PUT	/api/notifications/preferences	Read / update event and channel preferences
GET	/api/notifications/preview	Delivery-scheduling preview
GET	/api/notifications/email-preview	Render email preview
POST	/api/notifications/test	Send a test; optional channel selects one configured channel
GET	/api/notifications/log	Recent delivery log; limit 1–200, default 50
POST	/api/notifications/retry-failed	Owner-controlled failed-delivery retry

Operations, data, and updates

Method	Path	Purpose
GET	/api/operations, /api/logs	Operational overview / filtered logs
POST	/api/operations/diagnostics	Run installation diagnostics
GET	/api/operations/support-bundle	Download redacted diagnostics
GET	/api/data/info	Storage, integrity, and recovery information
POST	/api/data/backup	Create validated manual backup
POST	/api/data/test-restore	Non-destructive test; location is primary or secondary, optional existing filename
GET	/api/data/export	Download portable recovery JSON
POST	/api/data/export/encrypted	Download encrypted export using passphrase
POST	/api/data/preview, /api/data/import	Preview / apply recovery content; use backup plus optional passphrase for encrypted content
GET	/api/update/check	Read release/update information
POST	/api/update/prepare	Create validated pre-update backup and return manual update guidance

Mock-only fixture routes are development controls and are not part of the normal owner API. There is no endpoint that silently installs a new application release.

Adding to a collection

For POST /api/watch/add?region=us, use returned identifiers:

{
  "slug": "RETURNED_WATCH_ID",
  "collectionId": "RETURNED_COLLECTION_ID",
  "quantity": 2
}

Omit the collection fields for an ordinary watch. Use collectionName instead of collectionId to create a project. Do not send both. Quantity belongs to a collection membership; an existing membership retains its quantities/payments. The response includes alreadyWatched, alreadyMember, and the current workspace.

POST /api/collections accepts name, existing watched slugs, and optional budget. PUT /api/collections/:id can update name, budget, notifyReady, alertsOnly, and archived, plus replace slugs or append addSlugs (not both). A region supports at most 50 collections, and a collection at most 1,000 members.

In the current dev API, PUT /api/collections/:id also accepts boolean budgetRequired. GET /api/collections advertises capabilities.budgetAlerts; clients should require it and verify the returned saved setting before reporting success. Existing collections default to false. Collection readiness adds budget with state (off, unknown, over, or within), total, difference, currency, and reason. Unknown totals/differences are null. The flag is included in schema-v12/format-v8 recovery. Budget and condition edits establish a baseline and cancel obsolete pending/failed collection deliveries.

Updating a purchase plan

For PUT /api/collections/:id/items/:slug?region=us:

{
  "quantity": 2,
  "purchasedQuantity": 1,
  "paidTotal": 80.00,
  "targetPrice": 90.00
}

Desired quantity is 1–1,000 and purchased quantity cannot exceed it. paidTotal is the combined amount paid for purchased units, not a per-unit price; null means unknown. targetPrice is optional and shared with the watch across all collections. A cleared target disables the watch's combined available-at-target condition. Money uses the selected region's currency; no conversion or checkout fee calculation occurs.

Deleting this item URL removes only that membership. Posting a validated plan to it restores an absent membership and rejects a conflicting existing one. Collections return pricing/planning/readiness details, and GET /api/collections advertises capabilities.memberEditing, purchasePlanning, and watchWorkflow.

Product/collection workspace responses also include overview with ready watch IDs, target-matching watch IDs, and ready collection IDs. Use the returned workspace after a mutation rather than guessing readiness locally.

Activity queries and limits

GET /api/activity?scope=all&type=restock&delivery=sent&page=1&limit=20
GET /api/activity/export?region=us&from=2026-09-01&to=2026-09-07&format=json

Supported parameters include scope (enabled region or all, with region as an alternative), search, type, delivery, from, to, page, and limit. Delivery filters are all, sent, pending, failed, and not-sent. Types are all, restock, sold_out, price_change, status_change, new_product, and collection_ready.

The API clamps integer page sizes to 10–100 and defaults to 20; the UI offers 20/50/100. Responses contain events, count, page, limit, pages, and normalized filters. Date-only values use UTC day boundaries; a date-only to includes that calendar day via an exclusive next-day boundary. ISO timestamp upper bounds are exclusive.

Exports ignore pagination and include at most 10,000 filtered events; JSON reports truncated. Watchlist import requests are limited to 256 KiB and up to 1,000 selected products, while full recovery preview/import requests allow up to 256 MiB. Treat all exported owner data as private.

The current dev Activity API additionally returns an opaque snapshot, newCount, and snapshotReset. Pass the URL-encoded snapshot unchanged with subsequent requests using the same filters to exclude events appended after that boundary. newCount counts matching events above it. snapshotReset: true means retention/recovery removed the anchor; the response uses a fresh boundary. The browser holds the displayed rows until the owner refreshes if membership changes. Snapshot boundaries do not freeze delivery outcomes or protect records from retention. Exports ignore snapshots.

Saved views and alert explanations (current dev checkout)

These additive endpoints are present on current dev, not the published v1.2.0 binary. They use the existing owner session/origin/CSRF protections and ?region= convention.

Method	Path	Contract
GET	/api/views	{views:[...]} for this regional Store
POST	/api/views	{name,scope,filters}; scope is watchlist or browse; returns {ok,view,views}
PUT	/api/views/:id	{revision,name,filters?}; omitted filters retain the saved filters
DELETE	/api/views/:id	JSON body {revision}; removes the view, preserving watches/rules
GET	/api/watch/:slug/alerts	Effective configuration, schedule previews, real jobs and cooldowns for a watched product
GET	/api/collections/:id/alerts	The equivalent explanation for a collection

Views have id, name, scope, region, revision, and filters. Names are printable, at most 80 characters, and unique without case distinctions within each scope/Store. Limit: 30 views per Store, both scopes combined. Missing regional IDs return 404; duplicate names or stale revision edits/deletes return 409. Invalid filters/limits return 400. Each successful edit advances the revision. Store the returned revision and reopen after conflicts rather than overwriting another device's work.

Common filters: search, category, sort (name, price-low, price-high, availability; Watchlist also allows changed, added). Watchlist additionally accepts status (all, in, out, paused, purchased, wanted), collection (all, none, or an existing collection ID), overview (all, ready, target, collections), groupCollections (boolean), and layout (cards, compact). Browse uses availability (all, in, out, soon, unlisted) and watching (all, watched, unwatched). The all-category value is all for Watchlist and All for Browse. Search is limited to 200 characters; category to 100.

Watched products and collections include alertSummary. Workspace responses include a watchAlerts map so member summaries can refresh after collection changes. Explanation configuration describes saved effective rules; plans previews timing for new events; delivery contains up to 20 actual pending/processing/failed jobs; cooldowns gives active repeat-event limits. Do not render configuration as a queued job. Endpoints never expose channel credentials or notification URLs.

GET /healthz additionally reports packageVersion (standalone build metadata, falling back to the application version). Verify version as well as package metadata; a metadata file alone does not establish which executable is running. These changes use existing settings storage (owner_views), with no schema/export-format increment.