REST API

Every console operation is performed over this API. The master serves its own interactive schema; this page provides orientation.

Authoritative reference#

The master generates an interactive API reference from the running code and serves it alongside the console. The generated reference is always current for the version in use; a static endpoint list is not.

Authentication#

Every endpoint except login requires a bearer token. Exchange credentials for one:

$ curl -X POST https://master.studio.local:7443/auth/login \
    -d "{\"username\": \"admin\", \"password\": \"$ADMIN_PASSWORD\"}"

Send the token on every request:

$ curl https://master.studio.local:7443/workers \
    -H "Authorization: Bearer $TOKEN"

Job submission#

Most integrations require only this call. Provide a source the master can read, a preset id, and where to write the result:

A successful call returns 201 with the created job; the chunk plan is available immediately at GET /jobs/{id}/chunks. The master probes the source before planning, so an unreadable source path fails at submission rather than on a worker later. The body is strict: a field the schema does not define is rejected with 422, not ignored.

Push notifications#

The master delivers Web Push notifications for four events: a job completing, a job failing, a job parking pending approval, and a worker going offline. Delivery is per device — each browser in which push is enabled registers one subscription through the endpoints below. Which events a user receives is a per-account preference on the user record, described in the next section. All four endpoints require an authenticated user. The console-side procedure for enabling push on a device is covered in the notifications guide.

Safari on macOS and some locked-down browsers do not expose the Push API. The web console reports "Push notifications are not supported in this browser." in that case; the in-app fallback described below covers those sessions.

Returns {"public_key": …} — the base64url VAPID application-server key, passed as applicationServerKey to pushManager.subscribe(). The keypair is generated and persisted on first call and never changes afterward, so existing browser subscriptions stay valid across master restarts.

Returns 200 with the stored record: id (UUID), device_label and created_at (UTC). Registration is an upsert keyed on the endpoint URL: posting an endpoint that is already registered updates its keys, label and last-seen time and reassigns the row to the calling user rather than inserting a second row.

Lists the caller's own subscriptions, newest first — one row per browser or device in which push is enabled. Each row carries id, device_label and created_at only; the push endpoint and key material are never echoed. The master deletes a row on its own when the push service reports the subscription gone (browser profile removed, site data cleared, OS permission revoked), so a device can drop from this list without an explicit revocation. Transient delivery errors are logged and do not remove the row.

Revokes one subscription. Returns 204on success. An unknown id and another user's id are indistinguishable: both return 404 with the error type subscription_not_found. There is no administrator override, by design — a push subscription is a device credential, not an administrable resource.

Each notification deep-links to the relevant console page: /jobs/{job_id} for completion and failure, /review for pending approval, /workers for a worker going offline. Notifications for the same job or worker share a tag, so a later event replaces the earlier notification in the system tray instead of stacking. Delivery is best-effort: a push failure is logged and never interrupts the job or worker flow that raised the event.

Notification preferences#

Which events reach a user is a per-account setting, separate from the per-device subscriptions above. Current values are read from GET /auth/me; there is no GET /users/me. Each of the four booleans defaults to true.

Every field is optional; null or an omitted field leaves the stored value unchanged. The same body also accepts the mode and theme UI preferences. The response is the updated user record.

Resource index#

The web console has no private API; every console operation is available over these endpoints. The index below names every resource family the master registers. It is a map, not the contract — the OpenAPI schema is regenerated from the code on every route change, so the interactive reference at /docs on the master never drifts from the deployed version.

Conventions#

• Bearer auth on everything. A missing or expired token returns 401.
• Roles are enforced server-side. Some endpoints require an administrator; a valid token is not automatically a permitted one.
• Every response carries a request id. The x-request-idheader ties a call to the master's log lines — every log line emitted while handling the request carries the same id. Include it when reporting a problem.
• Login is rate-limited. Use an API token for anything automated.
• Live progress is a WebSocket. Do not poll a job for progress; subscribe, as the console does.