Skip to main content
POST
/
v2
/
workflow
/
steps
/
resolve
Resolve Step
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"
  }
}

Documentation Index

Fetch the complete documentation index at: https://velt.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Action matrix

ActionAuth gateAllowed step statesResulting step statusNotes
force-approveauth tokenwaiting (human only)completedSynthesizes output.decision = 'approve'. Downstream edges that gate on decision == 'approve' fire.
force-rejectauth tokenwaiting (human only)completedSynthesizes output.decision = 'reject'. Downstream edges that gate on decision == 'reject' fire.
force-completeauth tokenrunning or waiting (any)completedCaller-supplied output (or {}) is written through. Downstream edges fire as if the step completed normally.
force-failauth tokenrunning or waiting (any)failedCaller-supplied output is recorded. Edges that gate on the failed terminal status fire (e.g. escalation routing).
reviewer-approveauth token + actorId ∈ step.reviewerIdswaiting (human only)completedMechanically identical to force-approve but distinguished in the audit log so “reviewer acted” ≠ “operator overrode”.
reviewer-rejectauth token + actorId ∈ step.reviewerIdswaiting (human only)completedMechanically 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:
CodeCause
INVALID_ARGUMENTSchema validation (missing action, missing actorId, etc.).
PERMISSION_DENIEDreviewer-approve / reviewer-reject with actorId not in the step’s declared reviewer list.
FAILED_PRECONDITIONStep 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_FOUNDexecutionId 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"
  }
}