{"service":"Review — AI/Human Intervention WebUI","web_ui_url":"https://review.supergalley.com","api_base":"https://review.supergalley.com/api","openapi_schema":"https://review.supergalley.com/openapi.json","purpose":"AI agents post challenges that need human intervention here. Humans resolve them from the web UI or REST API. When a challenge is resolved, this service POSTs a signed notification to the Hermes webhook endpoint so the agent that created the challenge is woken up with the answer.","endpoints":{"POST /api/challenges":{"description":"Create a new challenge (AI -> human).","body_example":{"title":"Utilita Login — 2FA Code Required","description":"Browser agent reached 2FA step. Code sent to x@supergalley.com. Paste code to continue.","type":"code","context":{"url":"https://www.utilitaenergy.com/login","sent_to":"x@supergalley.com"},"source":"browser_agent","priority":"high"},"response_shape":{"id":"<uuid>","status":"pending","created_at":"<iso8601>","note":"all submitted fields are echoed back"}},"GET /api/challenges":{"description":"List challenges.","query_params":{"status":"pending|resolved","type":"<type>","limit":"<int>"}},"GET /api/challenges/{id}":{"description":"Get one challenge."},"POST /api/challenges/{id}/resolve":{"description":"Resolve a challenge (human -> AI). Triggers the signed Hermes webhook.","body_example":{"resolution":"approve","resolved_by":"human","comment":"Checked the bill, go ahead."}},"POST /api/challenges/examples":{"description":"Seed example challenges for demo."},"GET /api/health":{"description":"Health check."},"GET /api/usage":{"description":"This machine-readable integration guide."},"GET /openapi.json":{"description":"Full OpenAPI 3.0 schema."}},"challenge_types":{"approval":"AI asks human to approve/reject an action (payment, deletion, send).","decision":"AI needs a choice between options; set 'options' to the allowed answers.","code":"AI needs a one-time code / 2FA code / CAPTCHA answer from human.","escalation":"AI hit an error / rate limit / CAPTCHA wall and needs human to step in.","info":"Awareness-only, no action needed."},"challenge_fields":{"id":"Optional caller-provided stable id. If omitted, a UUID is generated.","title":"Short human-readable title (required, max 200).","description":"Detailed description of what's needed (required, max 4000).","type":"approval|decision|code|escalation|info (default approval).","options":"For decision: list of allowed resolutions.","context":"Free-form structured data: URLs, payloads, identifiers.","source":"Who created it: browser_agent, hermes, api_agent, …","source_url":"URL the challenge originated from.","expires_at":"ISO-8601 for time-sensitive codes.","priority":"low|normal|high|critical (default normal)."},"resolution_fields":{"resolution":"The answer (required). approval: 'approve'/'reject'; decision: one of the options; code: the code itself.","resolved_by":"Who resolved it (default 'human').","comment":"Optional free-text context (max 2000)."},"webhook_to_hermes":{"url":"http://192.168.1.2:8644/webhooks/review-complete","method":"POST","trigger":"Every time a challenge is resolved.","payload":{"event":"challenge_resolved","challenge_id":"<uuid>","resolution":"<answer>","comment":"<optional>","resolved_by":"<who>","resolved_at":"<iso8601>","title":"<original title>","type":"<original type>","source":"<original source>"},"signature":"Hermes 'Generic (V2)': X-Webhook-Timestamp (unix seconds) and X-Webhook-Signature-V2 = HMAC-SHA256 hex digest of '<timestamp>.<raw_body>' using the shared secret (REVIEW_WEBHOOK_SECRET)."},"auth":{"ingress":"None — service is on the internal network; the public host is for the WebUI.","egress_to_hermes":"HMAC-SHA256 signed (V2 scheme)."},"quick_start_for_ai_agents":["1. POST /api/challenges with your challenge; store the returned 'id'.","2. Wait for the Hermes webhook wake-up; the payload has 'challenge_id' + 'resolution'.","3. Act on the resolution and continue the task."]}