API docs

60 second quickstart

BASE_URL=https://humaneyes.app
API_KEY=he_app_xxx

# 1) Fund credits
curl -sS -X POST "$BASE_URL/api/v1/credits/deposits" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":25,"idempotency_key":"dep_abc123"}'

# 2) Submit job
curl -sS -X POST "$BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://example.com/img.jpg","question":"Is there a person in this image?","idempotency_key":"job_abc123"}'

# 3) Poll status
curl -sS "$BASE_URL/api/v1/jobs/<job_id>" \
  -H "Authorization: Bearer $API_KEY"

Authentication

Send API key as a bearer token in the Authorization header.

Authorization: Bearer he_app_xxxxx

Endpoints

POST /api/v1/credits/deposits

Required: amount, idempotency_key

POST /api/v1/jobs

Required: either image_url OR image_base64/image_file, plus question and idempotency_key

Optional: webhook_url

image_url must be publicly accessible over HTTP(S), resolve to a public host, and return an image content type.

image_base64 accepts JPEG/PNG/WEBP/GIF payloads up to 5MB raw (data URI or raw base64 + image_content_type).

On create, we run strict deterministic validation first. If validation passes, we atomically validate, lock submission credits, and queue.

POST /api/v1/jobs/:id/cancel

Cancel is allowed only before in_progress and idempotently unlocks escrow.

GET /api/v1/jobs/:id

Returns current state, status_version, lifecycle hints, and consensus metadata.

Supports conditional polling via ETag and If-None-Match (returns 304 when unchanged).

GET /api/v1/jobs/:id/transitions

Returns auditable state transition history with timestamps.

POST /api/v1/jobs/:id/appeal

Open an appeal during appeal_window_open/inconclusive/invalidated with reason and optional idempotency_key.

Response shape

{
  "ok": true,
  "data": {
    "id": 123,
    "state": "appeal_window_open",
    "status_version": 7,
    "result": "yes",
    "confidence": 0.67,
    "lifecycle": {
      "terminal": false,
      "terminal_reason": null,
      "outcome_type": "pending",
      "supply_delayed": false,
      "supply_delay_code": null,
      "should_poll": true,
      "next_action": "poll_status",
      "next_poll_after_seconds": 120
    },
    "consensus": {
      "resolution": "majority",
      "appeal_release_at": "2026-04-07T03:12:00Z",
      "invalidated": false,
      "inconclusive": false
    },
    "result_error": null,
    "state_timestamps": {
      "created_at": "2026-04-07T03:10:00Z",
      "result_returned_at": "2026-04-07T03:11:00Z"
    }
  },
  "error": null
}

{
  "ok": false,
  "data": null,
  "error": {
    "code": "insufficient_credits",
    "message": "Add credits before submitting jobs.",
    "next_step": "POST /v1/credits/deposits"
  }
}

Agents should use lifecycle.next_poll_after_seconds to avoid wasteful polling.

If lifecycle.supply_delayed is true, assignment is delayed by temporary human supply constraints.

Include webhook_url on job create to receive asynchronous result updates with retries.

Webhook headers: X-HumanEyes-Event-Id, X-HumanEyes-Timestamp, X-HumanEyes-Signature (HMAC SHA256).

Error codes

invalid_api_key

missing_idempotency_key

invalid_amount

missing_image_url

missing_image_input

invalid_image_url

invalid_image_input

image_not_public

image_unreachable

image_not_supported

image_too_large

missing_question

invalid_question_shape

forbidden_role

human_supply_unavailable

queue_saturated

human_supply_delayed

invalid_webhook_url

invalid_job_payload

insufficient_credits

job_not_found

job_not_cancellable

Validation failures are deterministic and safe to retry after fixing the payload with the same idempotency key.

Simulated money mode

Set PAYMENTS_MODE=simulated to run production-like flows without real-money rails.

Preferred single switch: LAUNCH_MODE=solo_pilot (one-human loop), LAUNCH_MODE=team_pilot (normal consensus with simulated money), or LAUNCH_MODE=production (live profile defaults).

In simulated mode, developer dashboard includes Test credit top-up, and withdrawal/payout processors can use failure injection knobs.

Optional env knobs: SIM_WITHDRAWAL_FAILURE_RATE, SIM_WITHDRAWAL_CONFIRM_DELAY_SECONDS, SIM_PAYOUT_RELEASE_FAILURE_RATE, SIM_FAUCET_MAX_AMOUNT_CENTS.