Skip to main content

Workflow Instances API

Workflow instance endpoints inspect and operate on live executions created by the visual workflow engine. They back the admin route /admin/workflows/instances/{instanceId} and approval decisions on request detail pages.

info

All endpoint paths below include the /workflow-engine mount and omit only the global /api/v1.0 prefix. The router requires authentication and the workflows.enabled feature.

Endpoints​

MethodEndpointDescription
GET/workflow-engine/instances/{instance_id}Read current instance state, context, and history.
POST/workflow-engine/instances/{instance_id}/approveApprove, reject, or revoke a suspended approval-node decision.
POST/workflow-engine/instances/{instance_id}/retryRetry execution from a specific node with optional context updates.

Definitions and manual execution are covered in Workflows API.

Instance Shape​

{
  "id": "instance-uuid",
  "definition_id": "definition-uuid",
  "status": "SUSPENDED",
  "current_node_id": "approval-1",
  "context": {
    "request": {
      "id": "request-uuid",
      "type": "access",
      "status": "pending"
    }
  },
  "history": [
    {
      "node_id": "trigger-1",
      "timestamp": "2026-06-29T10:00:00Z",
      "result": {
        "status": "completed"
      }
    }
  ],
  "created_at": "2026-06-29T10:00:00Z",
  "updated_at": "2026-06-29T10:01:00Z"
}

Common statuses are RUNNING, SUSPENDED, COMPLETED, FAILED, and CANCELLED. Clients should treat unknown status strings as displayable server-provided states.

Get Instance​

GET /workflow-engine/instances/{instance_id}

Returns the instance shape above. The admin instance viewer fetches the definition separately from /definitions/{definition_id} and overlays instance status onto the saved graph.

Use current_node_id to identify the active or suspended node. Use history to render prior node results, errors, approval decisions, and timestamps.

Approval Decision​

POST /workflow-engine/instances/{instance_id}/approve
{
  "decision": "approved",
  "notes": "Approved after privacy review."
}

decision supports:

ValueEffect
approvedRecords the user's vote. If quorum is satisfied, the workflow resumes from the next node or completes.
rejectedRecords rejection, fails the instance, and rejects the linked request when present.
pendingRevokes a previous decision and returns the approval state to pending when allowed.

The instance must be suspended at an approval node for normal approve/reject actions. Revocation can also apply to completed or failed approval instances when the service can identify the approval node from history.

Response examples:

{
  "message": "Vote recorded. Waiting for other approvers.",
  "instance_id": "instance-uuid",
  "status": "SUSPENDED",
  "approval_state": {}
}
{
  "message": "Approval granted, workflow resumed",
  "instance_id": "instance-uuid",
  "status": "COMPLETED"
}

Retry Instance Execution​

POST /workflow-engine/instances/{instance_id}/retry
{
  "node_id": "action-2",
  "context_updates": {
    "ticket_id": "INC-1042",
    "debug": true
  }
}

node_id is required. context_updates is optional and must be a JSON object. The service merges the supplied updates into instance context, resets execution from the requested node, runs the workflow, and returns the updated instance shape.

The admin instance viewer validates that retry context parses as a JSON object before calling this endpoint.

Request Synchronization​

When an instance context contains a linked workflow request, approval outcomes also update the request:

  • Approved workflow outcomes can mark the request approved and set reviewer notes.
  • Rejected workflow outcomes can mark the request rejected and set reviewer notes.
  • Revoked decisions can return the request to pending.

Recertification request outcomes can also update the associated recertification audit item.

Error Responses​

StatusMeaning
400Instance is not in the required state, retry context is invalid, or the retry node cannot be used.
401Missing or expired authentication.
403User is not authorized to decide the approval node.
404Instance not found.
500Execution or persistence failure.