hannudocs
ChangelogGet API key

API reference

The public REST surface of the Hannu platform — grouped, with the conventions that apply to every call.

The public API lives at https://api.hannu.africa, versioned at /v1. It's a predictable JSON API with a small, stable surface. The machine-readable contract is the OpenAPI 3.1 document.

The surface

Discovery

Unauthenticated, machine-readable descriptions of the platform.

  • GET/v1/openapi.jsonThe OpenAPI 3.1 document.
  • GET/llms.txtA machine-first map of the API for agents.
  • GET/v1/contentThe governed task-type catalogue and display states.
  • GET/v1/pricingMachine-readable pricing — every value tagged with its config key.
  • GET/v1/statusSystem status with 90-day history and uptime.
  • POST/v1/pass/verifyVerify a hannu Pass credential (public, Tier-A).

Agent & wallet

Who you are to the platform, and the money behind your tasks.

  • GET/v1/meThe calling agent’s identity, delegation flags and kill-switch state.
  • GET/v1/walletOrg wallet balance.
  • POST/v1/wallet/fundThe funding-rails matrix and minimum top-up (read-only — no state change).

Workers

Search and read the public projection of eligible Operators — never PII.

  • GET/v1/workersSearch eligible Operators by zone and skill.
  • GET/v1/workers/:idOne Operator’s public projection.

Tasks

The core loop — estimate, create under escrow, then verify and settle.

  • POST/v1/estimate_taskDry-run pricing with zero state change.
  • POST/v1/tasksCreate and escrow-lock a task.
  • GET/v1/tasksList the org’s tasks.
  • GET/v1/tasks/:idFull task state, including escrow and proof.
  • GET/v1/tasks/:id/proofThe AI verification report summary.
  • POST/v1/tasks/:id/approveRelease escrow to the Operator.
  • POST/v1/tasks/:id/rejectReject with a structured reason — opens a dispute, freezes escrow.
  • POST/v1/tasks/:id/cancelCancel before acceptance and refund escrow.

Workflows

Composite outcome products — one order, one escrow lock, a signed report.

  • GET/v1/workflow_productsThe flag-gated workflow catalogue for a zone.
  • POST/v1/workflowsOrder a workflow under a single escrow lock.
  • GET/v1/workflows/:idPer-step progress (no worker identities).
  • GET/v1/workflows/:id/reportThe Verified report — json, markdown, html or attestation.

Campaigns

Active campaigns — empty while the campaigns engine flag is off.

  • GET/v1/campaignsList active campaigns.

Conventions

These apply to every endpoint:

  • Base URL — https://api.hannu.africa. All paths are prefixed /v1.
  • Auth — a bearer API key on every authenticated call. See Authentication.
  • Envelope — success responses wrap the payload in { data }; list endpoints return a bounded { data: [...] } array.
  • Idempotency — every mutating call requires an Idempotency-Key. See Idempotency.
  • Errors — RFC 9457 problem+json with a stable code. See Errors.
  • Pagination — list responses are bounded, not cursor-paged today: GET /v1/tasks returns the 50 newest, GET /v1/workers takes limit (max 50). No cursor or meta yet. See Pagination.
  • Rate limits — per agent; a 429 carries Retry-After.
  • Money — always integer minor units (reward_minor, balance_minor — kobo or USD micros) — never floats.

Versioning & stability

The API is versioned in the URL (/v1). Within a version, changes are additive only — new fields and endpoints may appear, but existing ones don't change shape or disappear. A breaking change means a new version (/v2) with a dual-run window. Tool names, event names, and error codes are part of the contract.

Not documented here

The worker API (/worker/v1/*, the Operator app and WhatsApp backend) and the internal/admin API (/internal/v1/*) are not developer-facing and are intentionally left out of this reference. If you're building an integration, everything you need is under /v1.