Skip to main content
POST
/
v1
/
workflows
/
runs
/
{run_id}
/
hil-decisions
from retab import Retab

client = Retab()

# Approve a HIL block, optionally with edited data
result = client.workflows.runs.submit_hil_decision(
    run_id="run_abc123",
    block_id="hil-1",
    approved=True,
    modified_data={"amount": 1234.56},
    command_id="cmd_idempotent_abc",  # optional dedup key
)

print(result.submission_status)  # "accepted" / "already_received"

# Reject a HIL block
result = client.workflows.runs.submit_hil_decision(
    run_id="run_abc123",
    block_id="hil-1",
    approved=False,
)

{
  "submission_status": "accepted",
  "decision": {
    "run_id": "run_abc123",
    "block_id": "hil-1",
    "block_status": "waiting_for_hil",
    "decision_received": true,
    "decision_applied": false,
    "approved": true,
    "modified_data": { "amount": 1234.56 },
    "payload_hash": "sha256-abc",
    "received_at": "2026-05-01T14:30:00Z",
    "applied_at": null
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

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

Submit an approve/reject decision for a human-in-the-loop block on a workflow run. This endpoint is command-oriented:
  • it records the decision with Temporal as the source of truth
  • it returns decision receipt state, not a refreshed WorkflowRun
  • the run projection in Mongo may update shortly afterward
Use Get Run to refresh the projected run state after submission, or Get HIL Decision when you need command-side decision truth. Common outcomes:
  • submission_status="accepted": a new matching decision was accepted
  • submission_status="already_received": the same logical decision had already been received
If the block already has the opposite decision or is no longer eligible to accept a decision, the endpoint returns 409. 
from retab import Retab

client = Retab()

# Approve a HIL block, optionally with edited data
result = client.workflows.runs.submit_hil_decision(
    run_id="run_abc123",
    block_id="hil-1",
    approved=True,
    modified_data={"amount": 1234.56},
    command_id="cmd_idempotent_abc",  # optional dedup key
)

print(result.submission_status)  # "accepted" / "already_received"

# Reject a HIL block
result = client.workflows.runs.submit_hil_decision(
    run_id="run_abc123",
    block_id="hil-1",
    approved=False,
)

{
  "submission_status": "accepted",
  "decision": {
    "run_id": "run_abc123",
    "block_id": "hil-1",
    "block_status": "waiting_for_hil",
    "decision_received": true,
    "decision_applied": false,
    "approved": true,
    "modified_data": { "amount": 1234.56 },
    "payload_hash": "sha256-abc",
    "received_at": "2026-05-01T14:30:00Z",
    "applied_at": null
  }
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
run_id
string
required

Query Parameters

​
access_token
string | null

Body

application/json
​
block_id
string
required

ID of the HIL block being approved/rejected

​
approved
boolean
required

Whether the human approved the data

​
command_id
string | null

Optional idempotency key for deduplicating HIL decision commands

​
modified_data
Modified Data · object

Optional modified data supplied by the human reviewer

Response

Successful Response

​
submission_status
enum<string>
required

Decision submission lifecycle status: accepted for a newly accepted decision, already_received for a duplicate in-flight decision, or already_applied for a matching decision that has already been applied

Available options:
accepted,
already_received,
already_applied
​
decision
HILDecisionResource · object
required

Temporal-owned HIL decision state for the block