Skip to main content

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.

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​

RouteMethod
/api/v1/hitl/queueGET, POST
/api/v1/hitl/queue/{id}GET
/api/v1/hitl/queue/{id}/approvePOST
/api/v1/hitl/queue/{id}/rejectPOST
/api/v1/hitl/queue/{id}/overridePOST
/api/v1/hitl/queue/{id}/historyGET
/api/v1/hitl/statsGET
/api/v1/hitl/expirePOST

HITL Create Request​

POST /api/v1/hitl/queue

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

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​

RouteMethod
/api/v1/circuit-breaker/tripPOST
/api/v1/circuit-breaker/resetPOST
/api/v1/circuit-breaker/checkPOST
/api/v1/circuit-breaker/statusGET
/api/v1/circuit-breaker/historyGET
/api/v1/circuit-breaker/configGET, PUT
/api/v1/circuit-breaker/notificationsGET, POST
/api/v1/circuit-breaker/notifications/{id}PUT, DELETE
/api/v1/emergency-stopPOST
/api/v1/emergency-stop/releasePOST

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.

Last updated on