Skip to content
Workshape Catalyst Operator Docs

Jobs

List background jobs, newest first, without their payload

Section titled “List background jobs, newest first, without their payload”

GET /api/v1/instance/jobs

Operation
instance.jobs.list
Accepts
sessionCookie, sessionToken, accessToken
Scope
governance:read
Rights
audit.view
Effect
reading
Rate class
read

Parameters

  • limit integer in query, optional, default 50, minimum 1, maximum 200
  • cursor string in query, optional, minLength 1
  • kind string in query, optional, minLength 1
  • status JobStatusList in query, optional

Answers

  • 200 One page of the list

    application/json: object

    • items array of Job required
    • nextCursor string optional
  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Count the queued, running, failed and dead background jobs of each kind

Section titled “Count the queued, running, failed and dead background jobs of each kind”

GET /api/v1/instance/jobs/summary

Operation
instance.jobs.summary
Accepts
sessionCookie, sessionToken, accessToken
Scope
governance:read
Rights
audit.view
Effect
reading
Rate class
read

Answers

  • 200 The result

    application/json: object

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.

Queue a failed or dead background job again; superadmins only

Section titled “Queue a failed or dead background job again; superadmins only”

POST /api/v1/instance/jobs/{jobId}/retry

Operation
instance.jobs.retry
Accepts
sessionCookie, sessionToken
Scope
governance:write
Effect
changing
Rate class
write

Parameters

  • jobId string in path, required
  • Idempotency-Key string in header, optional, minLength 1, maxLength 255

Answers

  • 200 The result Sets Operation-Run-Id, Idempotent-Replayed.

    application/json: Job

  • 202 The call waits for somebody else to approve it. This is its Operation Run; read it again at Location. Sets Operation-Run-Id, Location, Idempotent-Replayed.

    application/json: OperationRun

  • 400 BAD_REQUEST: The request cannot be read.
  • 401 UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • 403 FORBIDDEN: The caller lacks the scope or the right this operation requires. POLICY_DENIED: The instance's policy does not allow this operation from here. details.operation names it. GUARDRAIL_BLOCKED: A guardrail refused the call. details.guardrailId names it. DECLINED: The person asked to approve the call declined it. details.by names them, details.comment holds their reason where they gave one.
  • 404 NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • 409 CONFLICT: The request conflicts with the current state of the resource. IDEMPOTENCY_KEY_REUSED: The Idempotency-Key was already used for another operation or another input. Send a new key. OPERATION_IN_PROGRESS: The first call with this Idempotency-Key has not ended, or it was interrupted and its outcome is not known (details.interrupted is true). details.operationRunId names its run. An interrupted call is never run again under its key: check what it changed, then send a new key. OPERATION_EXPIRED: The call waited for an approval until it expired, and nothing was executed. Call again with a new key. OUTPUT_NOT_RETAINED: The call with this Idempotency-Key completed, and its answer was too large to keep. Read the result from what the call changed.
  • 422 VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 429 RATE_LIMITED: The caller sent too many requests of this operation's rate class. details.retryAfterSeconds and the Retry-After header give the seconds to wait. The numbers are the instance's, set under rateLimits in its release config.
  • 500 INTERNAL: The instance failed. The message never carries details.