Skip to content
Workshape Catalyst Operator Docs

API reference

This is the reference of release 0.6.3, written from the openapi.json that the package @vivd-catalyst/api-contract ships. A running instance serves the reference of the operations it runs itself at /api/v1/docs, and the document behind it at /api/v1/openapi.json. Both ask for a signed-in person or an access token.

Every operation under /api/v1 of release 0.6.3, and the unversioned readiness probe /ready. Every error answers with the envelope ApiErrorResponse; its code is the stable part, its correlationId names the request in the instance's log.

Credentials

  • sessionCookie (cookie better-auth.session_token): The session of a person signed in through /api/auth, the mount owned by the sign-in library. Over HTTPS the browser carries the cookie as __Secure-better-auth.session_token. A changing request with this cookie must come from the instance's own origin or an allowed one.
  • sessionToken (Authorization: Bearer …): A session token a trusted backend obtained for one of its users from session_tokens.issue.
  • accessToken (Authorization: Bearer …): A short-lived access token of a service principal, obtained from access_tokens.exchange with an API key.
  • apiKey (Authorization: Bearer …): An API key of a service principal. It is presented only to access_tokens.exchange.
  • serverCredential (header x-server-credential): The instance's server credential, held by a trusted backend.

Errors

  • BAD_REQUEST: The request cannot be read.
  • UNAUTHENTICATED: No credential was presented, or the credential is not valid.
  • FORBIDDEN: The caller lacks the scope or the right this operation requires.
  • NOT_FOUND: The resource does not exist, is not visible to the caller, or the instance runs without this operation.
  • CONFLICT: The request conflicts with the current state of the resource.
  • VALIDATION_FAILED: Path, query or body do not match the operation's schema.
  • 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.
  • INTERNAL: The instance failed. The message never carries details.
  • 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.
  • 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.

Answer headers

  • Operation-Run-Id: The id of the Operation Run that records this call. Set on every answer of a call that got as far as a run, a refusal and a failure included.
  • Location: Where the Operation Run of a call that waits for an approval is read.
  • Idempotent-Replayed: true when the answer is the recorded one of an earlier call with the same Idempotency-Key.