HITL API

Endpoints for managing Human-in-the-Loop approval workflows.

List Pending Approvals

GET /api/hitl/pending

Query Parameters

Parameter	Type	Description
`queue`	string	Filter by queue
`tags`	string	Filter by tags (comma-separated)
`reviewerId`	string	Filter by assigned reviewer
`includeExpired`	boolean	Include timed-out approvals. Default: false
`limit`	number	Max results (default: 20)
`offset`	number	Pagination offset

Response

{
  "success": true,
  "data": [
    {
      "taskId": "dt_task_abc123",
      "planExecutionId": "dt_exec_xyz789",
      "stepId": "analyze-risk",
      "model": "opus",
      "queue": "gpu-queue",
      "confidence": 0.72,
      "summary": "Risk analysis identified 3 high-severity issues in sections 4.2, 5.1, and 8.3",
      "output": "Full analysis output text...",
      "prompt": "Analyze risks in the following clauses...",
      "tags": ["legal", "contract-review"],
      "createdAt": "2026-02-20T10:00:00Z",
      "waitingMs": 120000,
      "timeoutAt": "2026-02-20T11:00:00Z",
      "assignedTo": null
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Approve Task

POST /api/hitl/:taskId/approve

Request Body

{
  "comment": "Analysis looks thorough. Approved with minor clarification.",
  "modifiedOutput": "Corrected version of the output if reviewer made edits...",
  "reviewerId": "reviewer_jane"
}

All fields are optional. If modifiedOutput is provided, it replaces the agent's original output in the pipeline.

Response

{
  "success": true,
  "data": {
    "taskId": "dt_task_abc123",
    "status": "completed",
    "approvedAt": "2026-02-20T10:02:00Z",
    "approvedBy": "reviewer_jane",
    "comment": "Analysis looks thorough. Approved with minor clarification.",
    "wasModified": true
  }
}

Reject Task

POST /api/hitl/:taskId/reject

Request Body

{
  "reason": "Missing analysis of Section 7 indemnification clause.",
  "retry": true,
  "retryPrompt": "Re-analyze with special attention to Section 7.",
  "reviewerId": "reviewer_jane"
}

Field	Type	Required	Description
`reason`	string	Yes	Reason for rejection
`retry`	boolean	No	Re-queue with feedback. Default: false
`retryPrompt`	string	No	Modified prompt for retry
`reviewerId`	string	No	Reviewer identity

Response

{
  "success": true,
  "data": {
    "taskId": "dt_task_abc123",
    "status": "rejected",
    "rejectedAt": "2026-02-20T10:02:00Z",
    "rejectedBy": "reviewer_jane",
    "reason": "Missing analysis of Section 7 indemnification clause.",
    "retryTaskId": "dt_task_def456"
  }
}

When retry: true, a new task is created with the original prompt plus the rejection feedback. The new task ID is returned in retryTaskId. The original task remains in rejected status.

Get Approval History

GET /api/hitl/:taskId/history

Returns the full audit trail for a task's HITL lifecycle.

Response

{
  "success": true,
  "data": [
    {
      "action": "pending",
      "timestamp": "2026-02-20T10:00:00Z",
      "confidence": 0.72,
      "details": {
        "threshold": 0.85,
        "planExecutionId": "dt_exec_xyz789",
        "stepId": "analyze-risk"
      }
    },
    {
      "action": "assigned",
      "timestamp": "2026-02-20T10:00:01Z",
      "assignedTo": "reviewer_bob",
      "details": {
        "assignmentMethod": "round-robin"
      }
    },
    {
      "action": "escalated",
      "timestamp": "2026-02-20T10:30:00Z",
      "from": "reviewer_bob",
      "to": "reviewer_jane",
      "details": {
        "reason": "timeout",
        "escalationAfterMs": 1800000
      }
    },
    {
      "action": "approved",
      "timestamp": "2026-02-20T10:32:00Z",
      "reviewerId": "reviewer_jane",
      "comment": "Approved with edits.",
      "wasModified": true
    }
  ]
}

HITL Statistics

GET /api/hitl/stats

Returns aggregate HITL metrics.

Response

{
  "success": true,
  "data": {
    "pending": 3,
    "approvedToday": 12,
    "rejectedToday": 2,
    "avgWaitTimeMs": 180000,
    "avgConfidence": 0.78,
    "escalationRate": 0.15,
    "topReviewers": [
      { "id": "reviewer_jane", "approvals": 8, "rejections": 1 },
      { "id": "reviewer_bob", "approvals": 4, "rejections": 1 }
    ]
  }
}

Next Steps

WebSocket API -- Real-time HITL event subscriptions
HITL Guide -- Comprehensive HITL patterns and configuration

Templates WebSocket