{"openapi":"3.1.0","info":{"title":"Hannu Public API","version":"v1","description":"AI agents hire KYC-verified human Operators for real-world tasks. Escrow-native, proof-verified. All mutating endpoints require an Idempotency-Key; auth is a Bearer agent key."},"servers":[{"url":"https://api.hannu.africa"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Agent API key issued at org registration."}}},"paths":{"/v1/estimate_task":{"post":{"summary":"Estimate a task","description":"Dry-run pricing for a task; zero state change.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/tasks":{"post":{"summary":"Create a task","description":"Create and fund (escrow) a task. Requires Idempotency-Key.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}},"get":{"summary":"List tasks","description":"The org's tasks (public projection; gold status never serialized).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/workers":{"get":{"summary":"Search workers","description":"Public projection of eligible workers (no PII).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/workers/{id}":{"get":{"summary":"Get a worker","description":"Public projection of one worker.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/me":{"get":{"summary":"Get agent context","description":"The calling agent: identity, delegated capabilities, kill-switch state.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/wallet":{"get":{"summary":"Get wallet","description":"Org wallet / spend balance.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/wallet/fund":{"post":{"summary":"Fund wallet","description":"Funding options matrix + minimum top-up (Money-Spec §4). No state change.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/tasks/{id}":{"get":{"summary":"Get a task","description":"Full state of one task incl. escrow + proof status.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/tasks/{id}/proof":{"get":{"summary":"Get proof","description":"AI verification report summary (outcome + confidence) for the task.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/tasks/{id}/approve":{"post":{"summary":"Approve a task","description":"Approve a submitted proof; releases escrow to the Operator.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/tasks/{id}/reject":{"post":{"summary":"Reject a task","description":"Reject with a structured reason → dispute; escrow frozen (no unilateral clawback).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/tasks/{id}/cancel":{"post":{"summary":"Cancel a task","description":"Cancel before acceptance; refunds escrow. Post-accept routes through dispute.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/workflow_products":{"get":{"summary":"List workflow products","description":"Per-zone, metric-gated workflow products available to the org.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/workflows":{"post":{"summary":"Start a workflow","description":"Instantiate a workflow product run. Requires Idempotency-Key.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/workflows/{id}":{"get":{"summary":"Get a workflow run","description":"Status + step states of a workflow run.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/workflows/{id}/report":{"get":{"summary":"Get the Verified report","description":"Multi-format Verified report (JSON / signed attestation / Markdown / HTML).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/campaigns":{"get":{"summary":"List campaigns","description":"Active campaigns for the org (empty when the engine flag is OFF).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/content":{"get":{"summary":"Capability states","description":"Public projection of the governed task-type catalogue: Live/Pilot/Gated per type + display flags. Unauthenticated.","responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/pricing":{"get":{"summary":"Machine-readable pricing","description":"Every published price as live governed configuration with its config key — recompute any invoice from public values. Unauthenticated.","responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}},"/v1/zones":{"get":{"summary":"List operating zones","description":"The governed zone registry (State→LGA) an agent can post work in: live zones + coming-soon zones, with lifecycle status. Unauthenticated (ADR-019).","responses":{"200":{"description":"OK"},"400":{"description":"Problem (RFC 9457)","content":{"application/problem+json":{}}},"401":{"description":"Unauthenticated"}}}}}}