- Sells as: the
scheduler product (a product-scoped API key). This capability has no separate product-face contract — its public product route reuses the capability contract below; see the Edge route table's Product face row.
Durable background-job scheduling capability — register a one-shot (date), interval, or cron job with a callback_url; the scheduler persists it (own Postgres store, I4) and fires the callback when due, exactly once (single-owner Postgres advisory-lock election + FOR UPDATE SKIP LOCKED claim). A one-shot survives a restart because it is a durable row, not an in-memory job. The callback service token is resolved server-side (Infisical), never stored per-job or logged.
- Group: Comms & workflow
- Contract:
contracts/scheduler/v1/openapi.yaml
- Console: Manage the
scheduler product in the console →
- Runbook: operational checklist for
scheduler — internal (Vagary Labs ops; not part of this public site): docs/runbooks/capability-operations.md#scheduler
- Public base:
https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
- Auth: a product API key (
vgk_…) issued from the console — Authorization: Bearer vgk_…
- Product face (customer-keyed):
https://api.vagarylabs.com/product/v1/jobs
Edge route table
The routes this capability actually serves on the public edge — live-synced from GET https://api.vagarylabs.com/product/v1/_meta/catalog (snapshot v1). The metric is the request-granularity billing counter; the scope is the key permission required.
Product face (customer-keyed)
| Method | Path | Metric | Scope |
|---|
POST | /product/v1/jobs | job_operations | write |
Endpoints
| Method | Path | Summary |
|---|
POST | /v1/jobs | Register (upsert) a durable job with a callback_url |
GET | /v1/jobs | List the caller's org jobs |
GET | /v1/jobs/{job_id} | Get one job |
DELETE | /v1/jobs/{job_id} | Remove one job |
GET | /health | liveness |
GET | /metrics | Prometheus |
Schemas
JobRequest
| Field | Type | Description |
|---|
organization_id | string | product-tier tenant (I6) |
job_id | string | stable id, unique per org (upsert key) |
kind | string | |
callback_url | string | http(s) URL the scheduler POSTs when the job is due |
payload | object | arbitrary JSON forwarded to the callback |
run_at | string | required when kind=date |
interval_seconds | integer | required when kind=interval |
cron | object | required when kind=cron |
JobAccepted
| Field | Type | Description |
|---|
job_id | string | |
kind | string | |
status | string | |
next_run_at | string | |
Job
| Field | Type | Description |
|---|
job_id | string | |
organization_id | string | |
kind | string | |
callback_url | string | |
payload | object | |
interval_seconds | integer | |
cron | object | |
run_at | string | |
next_run_at | string | |
status | string | |
attempts | integer | |
last_error | string | |
Error
| Field | Type | Description |
|---|
error | string | |
Generated by scripts/gen-capability-docs.py from contracts/scheduler/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page. The Edge route table section is synced from the live edge catalog snapshot (v1) — re-sync with python3 scripts/sync-edge-catalog.py.