Skip to main content
Authenticated API

ACP (AI Cost & Performance) endpoints require a valid JWT Bearer token. Accessible via the API gateway.

HITL Approval Workflow

Human-in-the-loop approvals for sensitive agent actions. When agents attempt high-risk operations, approval requests are created and must be reviewed by authorized personnel before execution.

Create Approval Request​

POST /acp/approvals
Content-Type: application/json

Request Body:

{
  "agent_id": "agent_abc123",
  "action": "bulk_inventory_adjustment",
  "reason": "Weekly inventory reconciliation",
  "risk_level": "high",
  "context": {
    "items_affected": 45,
    "total_value_change": 2500.00,
    "location_id": "loc_123"
  },
  "expires_in_minutes": 60,
  "notify": ["manager@restaurant.com"],
  "callback_url": "https://api.example.com/approval-callback"
}

Response (201 Created):

{
  "approval_id": "appr_ghi789",
  "agent_id": "agent_abc123",
  "action": "bulk_inventory_adjustment",
  "status": "pending",
  "risk_level": "high",
  "expires_at": "2026-01-19T15:30:00Z",
  "approval_url": "https://cockpit.olympuscloud.ai/approvals/appr_ghi789",
  "created_at": "2026-01-19T14:30:00Z"
}

List Approval Requests​

GET /acp/approvals?status=pending&agent_id=agent_abc123

Query Parameters:

ParameterTypeDescription
statusstringFilter: pending, approved, denied, expired
agent_idstringFilter by requesting agent
risk_levelstringFilter: low, medium, high, critical
limitintegerResults per page
offsetintegerPagination offset

Response (200 OK):

{
  "approvals": [
    {
      "approval_id": "appr_ghi789",
      "agent_id": "agent_abc123",
      "agent_name": "restaurant-assistant",
      "action": "bulk_inventory_adjustment",
      "status": "pending",
      "risk_level": "high",
      "context": {
        "items_affected": 45,
        "total_value_change": 2500.00
      },
      "expires_at": "2026-01-19T15:30:00Z",
      "created_at": "2026-01-19T14:30:00Z"
    }
  ],
  "total": 3,
  "pending_count": 3
}

Get Approval Details​

GET /acp/approvals/{approval_id}

Response (200 OK):

{
  "approval_id": "appr_ghi789",
  "agent_id": "agent_abc123",
  "agent_name": "restaurant-assistant",
  "action": "bulk_inventory_adjustment",
  "reason": "Weekly inventory reconciliation",
  "status": "pending",
  "risk_level": "high",
  "context": {
    "items_affected": 45,
    "total_value_change": 2500.00,
    "location_id": "loc_123",
    "location_name": "Downtown Restaurant"
  },
  "history": [],
  "expires_at": "2026-01-19T15:30:00Z",
  "created_at": "2026-01-19T14:30:00Z"
}

Approve Request​

POST /acp/approvals/{approval_id}/approve
Content-Type: application/json

Request Body:

{
  "notes": "Reviewed and approved. Values match physical count.",
  "conditions": {
    "max_adjustment_per_item": 50
  }
}

Response (200 OK):

{
  "approval_id": "appr_ghi789",
  "status": "approved",
  "approved_by": "user_manager123",
  "approved_at": "2026-01-19T14:45:00Z",
  "notes": "Reviewed and approved. Values match physical count."
}

Deny Request​

POST /acp/approvals/{approval_id}/deny
Content-Type: application/json

Request Body:

{
  "notes": "Values exceed acceptable variance. Manual review required.",
  "reason_code": "VARIANCE_EXCEEDED"
}

Response (200 OK):

{
  "approval_id": "appr_ghi789",
  "status": "denied",
  "denied_by": "user_manager123",
  "denied_at": "2026-01-19T14:45:00Z",
  "notes": "Values exceed acceptable variance. Manual review required.",
  "reason_code": "VARIANCE_EXCEEDED"
}