HITL & Circuit Breaker API Reference

These are the two most important shared oversight APIs in the enterprise runtime. They are the surfaces teams reach for when policy evaluation is not enough and a human reviewer or platform team has to intervene.

Generated API reference

Both families are served by the Agent, and every route on this page is documented endpoint-by-endpoint in the generated Agent API reference (HITL and Circuit Breaker tags), rendered from the published OpenAPI spec. This page is the guide: it covers the auth rules, response envelopes, and verified payloads for those routes.

Authentication

HITL

• POST /api/v1/hitl/queue requires both X-Org-ID and tenant derived from Basic auth
• list, read, and stats flows are less strict, but you should still treat X-Org-ID as the standard organization header

Circuit breaker

• X-Org-ID is required
• X-User-ID is required for trip and reset
• X-User-Email is optional and is recorded when provided

Response Envelope

The HITL handler uses a wrapped JSON response shape, except GET /api/v1/hitl/status, which returns an unwrapped status object (enabled, mode, features):

{
  "success": true,
  "data": {},
  "meta": {
    "total": 10,
    "limit": 50,
    "offset": 0
  }
}

Circuit breaker endpoints use a simpler response envelope:

{
  "success": true,
  "data": { ... },
  "error": ""
}

No pagination metadata is included in circuit breaker responses.

HITL Queue Routes

Route	Method	Generated reference
/api/v1/hitl/queue	GET, POST	listHITLDecisions, createHITLDecision
/api/v1/hitl/queue/{id}	GET	getHITLDecision
/api/v1/hitl/queue/{id}/approve	POST	approveHITLDecision
/api/v1/hitl/queue/{id}/reject	POST	rejectHITLDecision
/api/v1/hitl/queue/{id}/override	POST	overrideHITLDecision
/api/v1/hitl/queue/{id}/history	GET	getHITLDecisionHistory
/api/v1/hitl/stats	GET	getHITLStats
/api/v1/hitl/expire	POST	expireHITLDecisions
/api/v1/hitl/status	GET	getHITLStatus

HITL Create Request

POST /api/v1/hitl/queue

Request fields, the same set as the HITLCreateRequest schema of createHITLDecision. client_id, original_query, request_type, triggered_policy_id, triggered_policy_name and trigger_reason are required:

• client_id
• user_id
• original_query
• request_type
• request_context
• triggered_policy_id
• triggered_policy_name
• trigger_reason
• severity
• eu_ai_act_article
• compliance_framework
• risk_classification
• expires_in_seconds
• notify_url (optional; the handler validates the URL before it creates the entry)

Example:

{
  "client_id": "advisor-ui",
  "user_id": "end-user-42",
  "original_query": "Approve a high-value transfer",
  "request_type": "high_value_transaction",
  "request_context": {
    "transaction_id": "txn-789"
  },
  "triggered_policy_id": "pol-high-value",
  "triggered_policy_name": "High Value Transaction Review",
  "trigger_reason": "Transfer exceeds configured review threshold",
  "severity": "high",
  "compliance_framework": "sebi",
  "risk_classification": "high",
  "expires_in_seconds": 3600
}

HITL Query And Review Routes

List queue

GET /api/v1/hitl/queue?status=pending&severity=high&limit=50&offset=0

Supported filters:

• status
• severity
• policy_id
• client_id
• user_id
• request_type
• limit
• offset
• order_by
• order_dir

These are the query parameters listHITLDecisions documents. When request_type is omitted, the list excludes wcp_step_gate entries; pass request_type=wcp_step_gate to list them.

Approve or reject

POST /api/v1/hitl/queue/{id}/approve
POST /api/v1/hitl/queue/{id}/reject

Verified review payload:

{
  "reviewer_id": "reviewer-123",
  "reviewer_email": "[email protected]",
  "reviewer_role": "Risk Officer",
  "comment": "Reviewed and approved"
}

Override

POST /api/v1/hitl/queue/{id}/override

Verified override payload:

{
  "justification": "Emergency override approved by CRO",
  "authorized_by_id": "cro-001",
  "authorized_by_email": "[email protected]",
  "authorized_by_role": "Chief Risk Officer"
}

History and stats

GET /api/v1/hitl/queue/{id}/history
GET /api/v1/hitl/stats
POST /api/v1/hitl/expire

Circuit Breaker Routes

Route	Method	Generated reference
/api/v1/circuit-breaker/trip	POST	tripCircuitBreaker
/api/v1/circuit-breaker/reset	POST	resetCircuitBreaker
/api/v1/circuit-breaker/check	POST	checkCircuitBreaker
/api/v1/circuit-breaker/status	GET	getCircuitBreakerStatus
/api/v1/circuit-breaker/history	GET	getCircuitBreakerHistory
/api/v1/circuit-breaker/config	GET, PUT	getCircuitBreakerConfig, updateCircuitBreakerConfig
/api/v1/circuit-breaker/notifications	GET, POST	listCircuitBreakerNotifications, createCircuitBreakerNotification
/api/v1/circuit-breaker/notifications/{id}	PUT, DELETE	updateCircuitBreakerNotification, deleteCircuitBreakerNotification
/api/v1/emergency-stop	POST	emergencyStop
/api/v1/emergency-stop/release	POST	emergencyStopRelease

Earlier spec revisions documented phantom activate/deactivate paths for this family; those never existed on the platform (the real routes are trip and reset) and were removed from the spec in the platform reconciliation.

Trip And Reset

Trip

POST /api/v1/circuit-breaker/trip

Verified trip request fields:

• scope
• scope_id
• reason
• comment
• duration_minutes

Supported scopes:

• global
• tenant
• client
• policy

Example:

{
  "scope": "tenant",
  "scope_id": "broker-india",
  "reason": "manual",
  "comment": "Pause tenant traffic pending investigation",
  "duration_minutes": 30
}

Reset

POST /api/v1/circuit-breaker/reset

Verified reset request fields:

{
  "scope": "tenant",
  "scope_id": "broker-india",
  "comment": "Issue resolved and traffic restored"
}

Check, Status, And History

Check

POST /api/v1/circuit-breaker/check

Verified request fields:

{
  "tenant_id": "broker-india",
  "client_id": "advisor-ui",
  "policy_id": "pol-high-value"
}

Read-only inspection

GET /api/v1/circuit-breaker/status
GET /api/v1/circuit-breaker/history

Config And Notifications

The circuit breaker implementation also exposes per-tenant config and notification CRUD. That makes it more than a panic button; it becomes a durable enterprise control surface.

GET /api/v1/circuit-breaker/config
PUT /api/v1/circuit-breaker/config
GET /api/v1/circuit-breaker/notifications
POST /api/v1/circuit-breaker/notifications
PUT /api/v1/circuit-breaker/notifications/{id}
DELETE /api/v1/circuit-breaker/notifications/{id}

Alias Routes

The emergency-stop aliases are functionally the same as trip and reset:

POST /api/v1/emergency-stop
POST /api/v1/emergency-stop/release

Use them when you want the operational naming to read more clearly in enterprise runbooks.

Related Guides

• Human-in-the-Loop Governance
• EU AI Act Compliance Guide
• SEBI AI/ML Compliance Guide
• RBI FREE-AI Compliance Guide