Scheduler API Reference

Operations

GET /api/v1/buildinfo

API alias for /buildinfo.json (same payload).

Responses:

GET /api/v1/jobengine/dag/job/{jobId}/children

Returns recorded child dependency edges for a JobEngine compatibility job. Scheduler runs currently expose only verified retry-of relationships.

Parameters:

Responses:

GET /api/v1/jobengine/dag/job/{jobId}/parents

Returns recorded parent dependency edges for a JobEngine compatibility job. Scheduler runs currently expose only verified retry-of relationships.

Parameters:

Responses:

GET /api/v1/jobengine/jobs

Lists JobEngine job records for the tenant. Scheduler runs are exposed as scheduler-run jobs so Console job views resolve to durable runtime state instead of a placeholder.

Responses:

GET /api/v1/jobengine/jobs/{jobId}

Returns one tenant-scoped JobEngine compatibility job record backed by a Scheduler run.

Parameters:

Responses:

GET /api/v1/jobengine/jobs/{jobId}/detail

Returns a tenant-scoped JobEngine compatibility job detail backed by the Scheduler run read model. Payload fields expose scheduler run evidence only; queue idempotency, lease, quota, dead-letter, and release-script proof fields remain null or explicitly unavailable when Scheduler has no durable proof.

Parameters:

Responses:

GET /api/v1/scheduler/doctor/trends

Returns aggregated health-check trend summaries from the Scheduler’s Doctor job.

Parameters:

Responses:

GET /api/v1/scheduler/doctor/trends/categories/{category}

Returns trend data points for all checks within a specific Doctor check category.

Parameters:

Responses:

GET /api/v1/scheduler/doctor/trends/checks/{checkId}

Returns trend data points for a specific Doctor health check.

Parameters:

Responses:

GET /api/v1/scheduler/doctor/trends/degrading

Returns Doctor health checks with degrading trends.

Parameters:

Responses:

GET /api/v1/scheduler/failure-signatures/best-match

Returns the best-matching failure signature for the given scope type, scope ID, and optional toolchain hash. Used to predict the likely outcome and error category for a new run based on historical failure patterns. Requires scheduler:read scope.

Parameters:

Responses:

GET /api/v1/scheduler/policies/simulations

Lists policy simulation runs for the tenant with optional filters by status and time range. Simulations are policy evaluations run in dry-run mode without committing verdicts. Requires policy.simulate scope.

Responses:

POST /api/v1/scheduler/policies/simulations

Enqueues a new policy simulation for the specified policy ID and version with the given SBOM input set. Returns 201 Created with the simulation ID and initial queued status. Requires policy.simulate scope.

Responses:

GET /api/v1/scheduler/policies/simulations/metrics

Returns aggregated simulation throughput metrics for the tenant including queue depth, processing rates, and median latency. Returns 501 if the metrics provider is not configured. Requires policy.simulate scope.

Responses:

POST /api/v1/scheduler/policies/simulations/preview

Enqueues a simulation and returns an immediate preview of the candidate count and estimated run scope before results are computed. Returns 201 Created with the simulation reference and preview payload. Requires policy.simulate scope.

Responses:

GET /api/v1/scheduler/policies/simulations/{simulationId}

Returns the full simulation run record for a specific simulation ID including status, policy reference, inputs, and projected verdict counts. Returns 404 if the simulation ID is not found. Requires policy.simulate scope.

Parameters:

Responses:

POST /api/v1/scheduler/policies/simulations/{simulationId}/cancel

Requests cancellation of a queued or running simulation. Returns 200 with the updated simulation record, or 404 if the simulation ID is not found. Requires policy.simulate scope.

Parameters:

Responses:

POST /api/v1/scheduler/policies/simulations/{simulationId}/retry

Retries a failed simulation, creating a new simulation record that re-uses the same policy and input configuration. Returns 201 Created with the new simulation ID. Requires policy.simulate scope.

Parameters:

Responses:

GET /api/v1/scheduler/policies/simulations/{simulationId}/stream

Server-Sent Events stream of real-time simulation progress events for a specific simulation ID. Clients should use the Last-Event-ID header for reconnect. Requires policy.simulate scope.

Parameters:

Responses:

GET /api/v1/scheduler/policy/runs

Lists policy run records for the tenant with optional filters by status, mode, and time range. Returns a paginated collection ordered by queue time. Requires policy.run scope.

Responses:

POST /api/v1/scheduler/policy/runs

Enqueues a new policy evaluation run for the specified policy ID and version. Returns 201 Created with the run ID and initial queued status. Requires policy.run scope.

Responses:

GET /api/v1/scheduler/policy/runs/{runId}

Returns the full policy run record for a specific run ID including status, policy reference, inputs, and verdict counts. Returns 404 if the run ID is not found. Requires policy.run scope.

Parameters:

Responses:

GET /api/v1/scheduler/runs

Lists scheduler runs for the tenant with optional filters by status, schedule ID, and time range. Returns a paginated result ordered by creation time. Requires scheduler:read scope.

Responses:

POST /api/v1/scheduler/runs

Creates and enqueues a new scheduler run for the specified schedule ID. Returns 201 Created with the run ID and initial status. Requires scheduler:operate scope.

Responses:

POST /api/v1/scheduler/runs/preview

Computes a dry-run impact preview for the specified scope without persisting a run record. Returns the set of artifacts that would be evaluated and estimated policy gate results. Requires scheduler:operate scope.

Responses:

GET /api/v1/scheduler/runs/queue/lag

Returns the current queue lag summary including the number of queued, running, and stuck runs per tenant. Used for SLO monitoring and alerting. Requires scheduler:read scope.

Responses:

GET /api/v1/scheduler/runs/{runId}

Returns the full run record for a specific run ID including status, schedule reference, impact snapshot, and policy evaluation results. Requires scheduler:read scope.

Parameters:

Responses:

POST /api/v1/scheduler/runs/{runId}/cancel

Cancels a queued or running scheduler run. Returns 404 if the run is not found or 409 if the run is already in a terminal state. Requires scheduler:operate scope.

Parameters:

Responses:

GET /api/v1/scheduler/runs/{runId}/deltas

Returns the impact delta records for a specific run, showing which artifacts were added, removed, or changed relative to the previous run. Requires scheduler:read scope.

Parameters:

Responses:

POST /api/v1/scheduler/runs/{runId}/retry

Retries a failed scheduler run by creating a new run linked to the original failure. Returns 404 if the run is not found or 409 if the run is not in a failed state. Requires scheduler:operate scope.

Parameters:

Responses:

GET /api/v1/scheduler/runs/{runId}/stream

Server-Sent Events stream of real-time run progress events for a specific run ID. Clients should use the Last-Event-ID header for reconnect. Requires scheduler:read scope.

Parameters:

Responses:

GET /api/v1/scheduler/schedules

Lists all schedules for the tenant with optional filters for enabled and deleted state. Returns a collection of schedule records including cron expression, timezone, mode, selection, and last run summary. Requires scheduler:read scope.

Responses:

POST /api/v1/scheduler/schedules

Creates a new release schedule with the specified cron expression, timezone, scope selection, and run mode. Returns 201 Created with the new schedule ID. Requires scheduler:operate scope.

Responses:

GET /api/v1/scheduler/schedules/{scheduleId}

Returns the full schedule record for a specific schedule ID including cron expression, timezone, selection, and last run summary. Returns 404 if the schedule is not found. Requires scheduler:read scope.

Parameters:

Responses:

DELETE /api/v1/scheduler/schedules/{scheduleId}

Soft-deletes a schedule. System-managed schedules cannot be deleted.

Parameters:

Responses:

PATCH /api/v1/scheduler/schedules/{scheduleId}

Applies a partial update to an existing schedule, replacing only the provided fields. Returns 200 with the updated record, or 404 if the schedule is not found. Requires scheduler:operate scope.

Parameters:

Responses:

POST /api/v1/scheduler/schedules/{scheduleId}/pause

Disables an active schedule, preventing future runs from being enqueued. Idempotent: returns 200 if the schedule is already paused. Requires scheduler:operate scope.

Parameters:

Responses:

POST /api/v1/scheduler/schedules/{scheduleId}/resume

Re-enables a paused schedule, allowing future runs to be enqueued on the configured cron expression. Idempotent: returns 200 if the schedule is already active. Requires scheduler:operate scope.

Parameters:

Responses:

POST /api/v1/scheduler/vuln/resolver/jobs

Enqueues a new vulnerability resolver job to fetch enriched vulnerability data for a given CVE or advisory set. Returns 201 Created with the job ID. Requires effective.write scope.

Responses:

GET /api/v1/scheduler/vuln/resolver/jobs/{jobId}

Returns the current status and result of a vulnerability resolver job by ID. Returns 404 if the job ID is not found. Requires findings.read scope.

Parameters:

Responses:

GET /api/v1/scheduler/vuln/resolver/metrics

Returns resolver job lag metrics including pending queue depth, processing rates, and backlog summary. Triggers a backlog breach notification if the depth exceeds the configured threshold. Requires findings.read scope.

Responses:

GET /api/v1/scheduler/workers

Returns an exact tenant-safe worker-registration summary and a bounded page of tenant-dedicated or shared Scheduler workers. Embedded execution is stated separately so an empty registry is not misreported as proof that nothing can run.

Parameters:

Responses:

GET /buildinfo.json

Image build provenance (module, gitSha, gitCommitTime, imageBuiltAt, branch) for drift detection.

Responses:

POST /events/conselier-export

Inbound webhook endpoint that receives Conselier VEX export events. Authentication is performed via HMAC-SHA256 signature validation on the request body. Rate-limited per the configured window. Returns 202 Accepted on success.

Responses:

POST /events/excitor-export

Inbound webhook endpoint that receives Excitor VEX export events. Authentication is performed via HMAC-SHA256 signature validation on the request body. Rate-limited per the configured window. Returns 202 Accepted on success.

Responses:

POST /graphs/build

Enqueues a graph build job to construct the reachability graph for the specified tenant scope. Returns 201 Created with the new job ID. Requires graph.write scope.

Responses:

POST /graphs/hooks/completed

Internal callback invoked by the Cartographer service to mark a graph job as completed and publish the completion event. Requires graph.write scope.

Responses:

GET /graphs/jobs

Lists graph jobs for the tenant with optional filters by status and job type. Returns a paginated collection ordered by creation time. Requires graph.read scope.

Parameters:

Responses:

POST /graphs/overlays

Enqueues a graph overlay job to apply incremental VEX or policy updates onto an existing reachability graph. Returns 201 Created with the new job ID. Requires graph.write scope.

Responses:

GET /graphs/overlays/lag

Returns lag metrics for overlay jobs including pending queue depth and processing rates. Used for SLO monitoring of graph overlay throughput. Requires graph.read scope.

Responses:

GET /healthz

Liveness probe endpoint for the Scheduler service. Returns HTTP 200 with a JSON body indicating the process is running. No authentication required.

Responses:

POST /internal/plugins/probe

Runs deterministic Scheduler plugin probes and returns the canonical plugin report.

Responses:

GET /internal/plugins/status

Returns Scheduler plugin discovery, admission, load, and current probe state.

Responses:

GET /readyz

Readiness probe endpoint for the Scheduler service. Returns HTTP 200 when the service is ready to accept traffic. No authentication required.

Responses: