Approval Endpoints

Human-in-the-loop (HITL) approval management. The approval-service runs on port 8004 and is proxied through the API gateway at http://localhost:8000.

Endpoints

Method	Path	Description
`POST`	`/api/v1/approvals`	Create an approval request
`GET`	`/api/v1/approvals`	List approval requests
`GET`	`/api/v1/approvals/{id}`	Get approval details
`POST`	`/api/v1/approvals/{id}/decide`	Approve or reject
`POST`	`/api/v1/approvals/escalate`	Escalate a pending approval

POST /api/v1/approvals

Create a new approval request. Typically called by the orchestration engine when an agent reaches an HITL checkpoint.


curl -X POST http://localhost:8000/api/v1/approvals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv-abc123",
    "agent_type": "rule_37",
    "checkpoint_type": "pre_filing",
    "payload": {
      "filing_type": "W-1",
      "entity_id": "well-001",
      "summary": "Rule 37 spacing exception for Smith Ranch #1"
    },
    "reviewer_strategy": "named_individual",
    "reviewer_id": "user-engineer-01"
  }'

Response (201):


{
  "approval_id": "apr-xyz789",
  "status": "pending",
  "checkpoint_type": "pre_filing",
  "created_at": "2026-04-10T15:00:00Z",
  "reviewer_id": "user-engineer-01"
}

GET /api/v1/approvals

List approval requests with optional filters.


curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/approvals?status=pending&agent_type=rule_37"

Parameter	Type	Description
`status`	string	Filter: `pending`, `approved`, `rejected`, `modified`
`agent_type`	string	Filter by agent type
`limit`	int	Page size (default 20)
`offset`	int	Pagination offset

Response (200):


{
  "approvals": [
    {
      "approval_id": "apr-xyz789",
      "status": "pending",
      "checkpoint_type": "pre_filing",
      "agent_type": "rule_37",
      "created_at": "2026-04-10T15:00:00Z"
    }
  ],
  "total": 5
}

POST /api/v1/approvals/{approval_id}/decide

Approve, reject, or request modifications.

Requires the reviewer or admin role at the gateway, plus the hitl.approve permission at the service (R42d).


curl -X POST http://localhost:8000/api/v1/approvals/apr-xyz789/decide \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved",
    "comments": "Filing package looks complete. Approved for submission."
  }'

Field	Type	Required	Description
`decision`	string	Yes	`approved`, `rejected`, or `modified`
`reviewer_id`	string	No	Legacy fallback (R42d): the reviewer is resolved from the authenticated identity (the gateway-stamped `X-User-Id`); supply this only from header-less internal callers
`comments`	string	No	Review comments
`modifications`	object	No	Requested changes (when decision is `modified`)

All decisions are recorded in the immutable audit trail. They cannot be modified or deleted after submission.

POST /api/v1/approvals/escalate

Escalate a pending approval that has not been acted on. Like /decide, this requires the hitl.approve permission at the service (R42d).


curl -X POST http://localhost:8000/api/v1/approvals/escalate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "approval_id": "apr-xyz789",
    "reason": "Original reviewer unavailable, deadline in 24 hours"
  }'