Scheduling

8 operations. {prefix} is the route prefix passed to MapAgentPrism; the template uses /agentprism.

GET {prefix}/api/jobs

Operation ID: AgentPrismListJobs

Lists jobs, filtered by kind, status, or schedule.

Every queued unit of work shares this queue — scheduled runs, retention cleanups, webhook deliveries, and queued agent runs — so filter by ‘kind’ to narrow it. ‘scheduleId’ returns the executions of one schedule. Job items are not included here; read them from the single-job endpoint. Paging is offset based, with ‘skip’ defaulting to 0 and ‘take’ to 50.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
kind	query	no	JobKind	—
status	query	no	JobStatus	—
scheduleId	query	no	string (uuid)	—
skip	query	no	integer (int32)	pattern `^-?(?:0\
take	query	no	integer (int32)	pattern `^-?(?:0\

Response	Body	Headers
200 OK	application/json → array of JobRecord	—

GET {prefix}/api/jobs/{id}

Operation ID: AgentPrismGetJob

Gets a job and its items.

This is the endpoint to poll after queuing work: it carries the job’s status and attempt count together with its items, each with its own status, so partial progress is visible while the job is still running. A failed job keeps its error text here rather than only in the logs. An unknown id, or one belonging to another tenant, returns 404.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
id	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	application/json → JobDetailResponse	—

POST {prefix}/api/jobs/{id}/cancel

Operation ID: AgentPrismCancelJob

Cancels a job.

Only a job in the Pending, Leased, or Running status can be canceled. The executing worker checks the cancellation request between items and stops cooperatively.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
id	path	yes	string (uuid)	—

Response	Body	Headers
204 No Content	—	—

GET {prefix}/api/schedules

Operation ID: AgentPrismListSchedules

Lists a tenant’s schedules.

Enabled and disabled schedules are returned together; ‘enabled’ tells them apart. Each entry carries ‘nextRunAt’ as computed at the last save and ‘lastRunAt’ from the last execution, which is the quickest way to see that a schedule has stopped firing. A schedule with no cron expression never fires on its own and exists only to be triggered by hand.

Authorization: bearer authentication; Admin role policy when that policy is registered; PlatformRead API-key scope.

Response	Body	Headers
200 OK	application/json → array of JobSchedule	—

GET {prefix}/api/schedules/{name}

Operation ID: AgentPrismGetSchedule

Gets a single schedule.

The response is the definition, including the stored payload the schedule fires with; the jobs it produced are read from the job endpoints, filtered by this schedule’s id. Names are scoped to the calling tenant, and an unknown name returns 404.

Authorization: bearer authentication; Admin role policy when that policy is registered; PlatformRead API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
200 OK	application/json → JobSchedule	—

PUT {prefix}/api/schedules/{name}

Operation ID: AgentPrismSaveSchedule

Creates or updates a schedule.

The cron expression and time zone are validated here; the next run time is computed at save time. The payload cannot exceed the MaxItemsPerJob limit.

Authorization: bearer authentication; Admin role policy when that policy is registered; PlatformAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Request body (required):

• application/json → JobScheduleSaveRequest

Response	Body	Headers
200 OK	application/json → JobSchedule	—

DELETE {prefix}/api/schedules/{name}

Operation ID: AgentPrismDeleteSchedule

Deletes a schedule.

The schedule stops firing, but jobs it already queued are not withdrawn — cancel those individually if they must not run. Job history keeps pointing at the deleted schedule’s id, so past executions stay traceable. To pause a schedule instead, save it with ‘enabled: false’. An unknown name returns 404.

Authorization: bearer authentication; Admin role policy when that policy is registered; PlatformAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
204 No Content	—	—

POST {prefix}/api/schedules/{name}/trigger

Operation ID: AgentPrismTriggerSchedule

Runs a schedule immediately, without waiting for the cron schedule.

The job is queued, not executed inline: the response is the queued job record, so poll the job endpoint for the outcome. The body is optional — without one the schedule’s stored payload is used, and a body’s payload overrides it for this run only without changing the schedule. A trigger fires even when the schedule is disabled, and it does not move ‘nextRunAt’. The payload’s item count is capped by the same limit that applies on save.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Request body (optional):

• application/json → JobTriggerRequest

Response	Body	Headers
200 OK	application/json → JobRecord	—