Resolve Step

POST /v2/workflow/steps/resolve

Resolve Step

cURL

curl --request POST \
  --url https://api.velt.dev/v2/workflow/steps/resolve \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "executionId": "<string>",
    "stepId": "<string>",
    "action": "<string>",
    "actorId": "<string>",
    "output": {},
    "reason": "<string>"
  }
}
'

{
  "result": {
    "resolved": true,
    "executionId": "exec_1777374504255_xzy43k9q",
    "stepId": "step_agent-draft_..._lwofay__to__human-brand",
    "action": "force-complete"
  }
}

Use this API to resolve a step that’s currently running or waiting. The endpoint supports two families of actions:

• Admin-grade overrides (force-approve, force-reject, force-complete, force-fail) — break a stuck step out of waiting or terminate a running step with an admin-supplied output. Audit log records the actor as an operator override.
• Reviewer-scoped decisions (reviewer-approve, reviewer-reject) — record a reviewer’s approve/reject decision through the API instead of through the comment-reply flow. Auth-gated to userIds in the step’s declared reviewer list.

Every resolve writes a step.overridden audit event with { actorId, action, reason, decision }.

Endpoint

POST https://api.velt.dev/v2/workflow/steps/resolve

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

executionId · string · required

The execution containing the step.

stepId · string · required

The step to resolve.

action · string · required

One of force-approve / force-reject / force-complete / force-fail / reviewer-approve / reviewer-reject. See the action matrix below.

actorId · string · required

1–256 chars. For force-* actions, the operator’s identifier. For reviewer-* actions, must equal a userId declared in the step’s reviewer list — otherwise the request is rejected with PERMISSION_DENIED.

output · object

Optional. Admin-supplied output for force-complete / force-fail. Ignored for approve/reject actions — decision, approved, and approvalReply are computed authoritatively by the engine.

reason · string

≤ 2000 chars. Recorded on the audit event.

Action matrix

Action	Auth gate	Allowed step states	Resulting step status	Notes
force-approve	auth token	waiting (human only)	completed	Synthesizes output.decision = 'approve'. Downstream edges that gate on decision == 'approve' fire.
force-reject	auth token	waiting (human only)	completed	Synthesizes output.decision = 'reject'. Downstream edges that gate on decision == 'reject' fire.
force-complete	auth token	running or waiting (any)	completed	Caller-supplied output (or {}) is written through. Downstream edges fire as if the step completed normally.
force-fail	auth token	running or waiting (any)	failed	Caller-supplied output is recorded. Edges that gate on the failed terminal status fire (e.g. escalation routing).
reviewer-approve	auth token + actorId ∈ step.reviewerIds	waiting (human only)	completed	Mechanically identical to force-approve but distinguished in the audit log so “reviewer acted” ≠ “operator overrode”.
reviewer-reject	auth token + actorId ∈ step.reviewerIds	waiting (human only)	completed	Mechanically identical to force-reject. Same audit distinction.

Authority-of-record. For all approve/reject actions (admin and reviewer), the engine computes decision, approved, and approvalReply itself. Caller-supplied output keys with the same names cannot override them. Other keys in output pass through. This prevents a reviewer from sending action: 'reviewer-reject' with output: { decision: 'approve' } and routing edges as an approval while the audit log records a rejection.

reviewer-reject and force-reject do not populate output.rejectedBy / output.rejectorMandatory. Those fields are only set on the natural Record Reviewer Decision aggregator path. If you drive loop regions via reviewer-reject, the default loop predicate (decision == 'reject' && rejectorMandatory == true) won’t fire — supply an explicit onIterationReject.when predicate that filters on decision alone.

Example Requests

Reviewer approves through the API

{
  "data": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "stepId": "step_agent-draft_..._lwofay__to__human-legal",
    "action": "reviewer-approve",
    "actorId": "u_legal_01",
    "reason": "looks good"
  }
}

Admin force-completes a stuck blocking-agent step

{
  "data": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "stepId": "step_blocking-agent_...",
    "action": "force-complete",
    "actorId": "ops_jane",
    "output": { "summary": "Manually closed; agent hung past deadline" },
    "reason": "Agent stuck on retry; closing to unblock execution"
  }
}

Admin force-fails a step to trigger an escalation edge

{
  "data": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "stepId": "step_agent-draft_..._lwofay__to__human-brand",
    "action": "force-fail",
    "actorId": "ops_jane",
    "reason": "Reviewer on PTO indefinitely; routing to escalation edge"
  }
}

Response

Success Response

{
  "result": {
    "resolved": true,
    "executionId": "exec_1777374504255_xzy43k9q",
    "stepId": "step_agent-draft_..._lwofay__to__human-brand",
    "action": "force-complete"
  }
}

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "FAILED_PRECONDITION"
  }
}

Errors:

Code	Cause
INVALID_ARGUMENT	Schema validation (missing action, missing actorId, etc.).
PERMISSION_DENIED	reviewer-approve / reviewer-reject with actorId not in the step’s declared reviewer list.
FAILED_PRECONDITION	Step is already terminal, step is not in an allowed state for the action (e.g. force-approve on a non-human step), or the underlying transition CAS rejected the change.
NOT_FOUND	executionId or stepId does not exist.

Workspace-admin RBAC is post-GA. Today the force-* actions gate on the standard auth token only. Until role-based access lands, restrict who can call this endpoint inside your own application.

{
  "result": {
    "resolved": true,
    "executionId": "exec_1777374504255_xzy43k9q",
    "stepId": "step_agent-draft_..._lwofay__to__human-brand",
    "action": "force-complete"
  }
}