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 the core routes are 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 — including several live routes that are not yet in the published spec, which remain fully documented here.

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:

{
  "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	Not yet in the published OpenAPI specs; documented below
/api/v1/hitl/queue/{id}/history	GET	Not yet in the published OpenAPI specs; documented below
/api/v1/hitl/stats	GET	Not yet in the published OpenAPI specs; documented below
/api/v1/hitl/expire	POST	Not yet in the published OpenAPI specs; documented below

HITL Create Request

POST /api/v1/hitl/queue

The request schema shown for createHITLDecision in the published spec differs from the verified handler fields below; treat the fields below as authoritative for the live platform.

Verified request fields:

• 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

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
• limit
• offset
• order_by
• order_dir

The published spec for listHITLDecisions currently documents only the org_id, status, and limit parameters; the remaining filters are live but not yet in the spec.

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