Scheduler

Sellable product

This capability is granted by an API key scoped to the `` product (product face). See the product reference below.

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
• 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

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.