Jobengine API Reference

Operations

GET /api/v1/buildinfo

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

Responses:

GET /api/v1/compliance/summary

Returns a compliance summary only for the validated claim tenant, including signed/unsigned packs, attestations, lifecycle, and mirror sync status. An optional tenant query value is only an equality check.

Parameters:

Responses:

POST /api/v1/export/offline-seed

Generates a ZIP archive for the validated claim tenant, optionally including binary content and provenance. An optional tenantId body field is only an equality check and cannot select another tenant.

Responses:

POST /api/v1/import/offline-seed

Imports an offline-seed export archive into the validated claim tenant. The archive is verified with the same SDK that backs stella verify offline-seed; only VERIFIED with no findings imports, and every other verdict is refused with its finding codes and an audit row. The tenant named inside the archive is ignored - packs land in the caller’s tenant.

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/jobengine/quotas/usage

Counts persisted run records created for the authenticated tenant in the current UTC day, without list pagination. Includes every run state and retry record; this is usage, not a licence entitlement or an enforcement decision.

Responses:

GET /api/v1/mirrors

Returns mirror registrations only for the validated claim tenant. An optional tenant query value is only an equality check; there is no global or cross-tenant listing mode.

Parameters:

Responses:

POST /api/v1/mirrors

Creates or updates a mirror registration within the validated claim tenant, associating a tenant-keyed mirror ID with an upstream URL and enabled state. The same mirror ID remains independent across tenants.

Responses:

POST /api/v1/mirrors/{id}/sync

Records a sync outcome for the specified mirror ID within the validated claim tenant. A missing ID and a same-ID foreign-tenant mirror both return the same non-enumerating 404.

Parameters:

Responses:

GET /api/v1/packs

Returns policy packs for the validated claim tenant, optionally excluding deprecated packs. An optional tenant query value is only an equality check and cannot select another tenant.

Parameters:

Responses:

POST /api/v1/packs

Uploads a new policy pack as base64-encoded content with optional signature and provenance attachment. The validated tenant claim is the sole tenancy authority; an optional tenantId body field is only an equality check. Returns 201 Created with the tenant-keyed registered pack record and assigned pack ID.

Responses:

POST /api/v1/packs/re-envelope

Bulk re-envelope the claim tenant’s pack corpus under the configured active verification root. Production rejects retiring, revoked, foreign, or mismatched key material (resumable, offline-capable; VKR-004).

Responses:

POST /api/v1/packs/stream

Streams a four-byte big-endian bounded JSON descriptor followed by exact content and optional provenance segments; the authenticated claim remains the sole tenant authority.

Parameters:

Responses:

GET /api/v1/packs/{packId}

Returns the metadata record for the specified pack ID within the authenticated tenant. The tenant-keyed lookup returns a non-enumerating 404 when no pack is visible to that tenant; it does not disclose whether the same pack ID exists for another tenant. A configured installation tenant allowlist can still return 403.

Parameters:

Responses:

GET /api/v1/packs/{packId}/attestations

Returns attestation records for the specified pack within the validated claim tenant. No records and a same-ID pack owned by another tenant both return the same non-enumerating 404.

Parameters:

Responses:

POST /api/v1/packs/{packId}/attestations

Attaches a typed attestation document to a pack in the validated claim tenant as base64-encoded content. The type field identifies the attestation kind (e.g., sbom, scan-result). Returns 201 Created with the stored attestation record. Returns 400 if type or content is missing or the content is not valid base64.

Parameters:

Responses:

POST /api/v1/packs/{packId}/attestations/stream

Streams a four-byte big-endian bounded JSON descriptor followed by one exact attestation segment under the authenticated claim tenant.

Parameters:

Responses:

GET /api/v1/packs/{packId}/attestations/{type}

Downloads a specific attestation type within the validated claim tenant and includes X-Attestation-Digest for integrity verification. A missing pack/type and a same-ID foreign-tenant artifact both return the same non-enumerating 404.

Parameters:

Responses:

GET /api/v1/packs/{packId}/content

Downloads the specified pack’s binary content within the authenticated tenant as an octet-stream, with X-Content-Digest for integrity verification. The tenant-keyed lookup returns a non-enumerating 404 when no pack is visible to that tenant; it does not disclose whether the same pack ID exists for another tenant. A configured installation tenant allowlist can still return 403.

Parameters:

Responses:

GET /api/v1/packs/{packId}/lifecycle

Returns lifecycle state for the specified pack within the validated claim tenant. A missing record and a same-ID foreign-tenant record both return the same non-enumerating 404.

Parameters:

Responses:

POST /api/v1/packs/{packId}/lifecycle

Transitions a pack in the validated claim tenant to a new lifecycle state (e.g., active, deprecated, archived) with optional notes. Returns the updated lifecycle record; foreign-tenant identity is never a tenancy source.

Parameters:

Responses:

GET /api/v1/packs/{packId}/manifest

Returns a structured manifest for the specified pack within the authenticated tenant, including origin and seed generation when applicable. The tenant-keyed lookup returns a non-enumerating 404 when no pack is visible to that tenant; it does not disclose whether the same pack ID exists for another tenant. A configured installation tenant allowlist can still return 403.

Parameters:

Responses:

GET /api/v1/packs/{packId}/parity

Returns parity status for the specified pack within the validated claim tenant. A missing record and a same-ID foreign-tenant record both return the same non-enumerating 404.

Parameters:

Responses:

POST /api/v1/packs/{packId}/parity

Records parity status for a pack in the validated claim tenant, with optional notes. Returns the updated parity record; foreign-tenant identity is never a tenancy source.

Parameters:

Responses:

GET /api/v1/packs/{packId}/provenance

Downloads the provenance document attached to the specified pack within the validated claim tenant as a JSON file. The response includes an X-Provenance-Digest header when a digest is stored. A missing or foreign-tenant pack/provenance returns the same non-enumerating 404.

Parameters:

Responses:

POST /api/v1/packs/{packId}/signature

Replaces the upload-owned current signature for a tenant-keyed pack while preserving any immutable seed envelope. Production verifies only with the configured active root; caller PEM overrides are restricted to Development/Testing. Returns 400 for retired, foreign, or invalid verification material.

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:

GET /doctor/jobengine-web/checks

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: