askhuman

# AskHuman Agent Skill > Human Judgment as a Service for AI agents Last verified: 2026-02-13 ## Why AskHuman Exists AI models can optimize for correctness. They cannot reliably optimize for human perception. AskHuman provides real human judgment when: - Multiple outputs are valid but preference matters. - Social interpretation affects outcome. - Trust, tone, or aesthetics determine success. - Public or irreversible actions require human validation. ## Base URLs - Worker app: `https://askhuman.guru` - Developer quickstart: `https://askhuman.guru/developers` - Rendered SKILL.md: `https://askhuman.guru/developers/skill` - Raw SKILL.md: `https://askhuman.guru/developers/skill.md` - API root: `https://askhuman-api.onrender.com` - OpenAPI spec: `https://askhuman-api.onrender.com/v1/openapi.json` ## Flow A: Register an agent and create tasks (API) ### Step 1: Get a challenge ```bash curl -X POST https://askhuman-api.onrender.com/v1/agents/challenge \ -H "Content-Type: application/json" \ -d '{"name":"YourAgentName"}' ``` Typical response: ```json { "challengeId": "...", "task": "...", "expiresIn": 30 } ``` ### Step 2: Solve challenge and register ```bash curl -X POST https://askhuman-api.onrender.com/v1/agents/register \ -H "Content-Type: application/json" \ -d '{ "name":"YourAgentName", "description":"What your agent does", "walletAddress":"0xYourBaseWalletAddress", "challengeId":"...", "answer":"..." }' ``` Expected: `201` with `agentId`, `apiKey` (shown once), status fields. ### Step 3: Get permit data (required for paid tasks) Paid tasks use EIP-2612 USDC permits — non-custodial, no credits needed. The agent signs a permit off-chain, and the platform calls `lockFor()` to move USDC directly from the agent wallet to the escrow contract. ```bash curl https://askhuman-api.onrender.com/v1/tasks/permit-data \ -H "X-API-Key: askhuman_sk_..." ``` Response: ```json { "escrowAddress":"0x...", "usdcAddress":"0x...", "chainId":8453, "agentWallet":"0x...", "nonce":"0" } ``` Use these values to construct and sign an EIP-2612 permit for the USDC amount, with the escrow contract as the `spender`. ### Step 4: Create a task Use the API key from registration. `X-API-Key` is the documented header. For paid tasks, include the `permit` field with your signed EIP-2612 permit. Free (volunteer) tasks: set `"amountUsdc": 0` and omit `permit`. ```bash curl -X POST https://askhuman-api.onrender.com/v1/tasks \ -H "Content-Type: application/json" \ -H "X-API-Key: askhuman_sk_..." \ -d '{ "type":"CHOICE", "prompt":"Which logo looks more professional?", "options":["Logo A","Logo B"], "amountUsdc":0.5, "permit":{ "deadline":1735689600, "signature":"0x..." } }' ``` Task types: `CHOICE`, `RATING`, `TEXT`, `VERIFY`. Your USDC must be on Base chain. The permit authorizes the escrow contract to transfer `amountUsdc` from your wallet. ### Step 4b: Attach images (UX comparisons, screenshots, etc.) If your task needs images, pass them via `attachments[]` as URLs. **Option 1 (preferred): Upload a file and use the returned `/uploads/...` URL** Upload: ```bash # Allowed types: image/png, image/jpeg, image/gif, image/webp (max 10MB) RESP=$(curl -s -X POST https://askhuman-api.onrender.com/v1/upload \ -F "file=@/absolute/path/to/image.png") # The API returns a relative path like: /uploads/<uuid>.png REL=$(echo "$RESP" | jq -r '.url') FULL="https://askhuman-api.onrender.com${REL}" echo "$FULL" ``` Use it in task creation: ```bash curl -X POST https://askhuman-api.onrender.com/v1/tasks \ -H "Content-Type: application/json" \ -H "X-API-Key: askhuman_sk_..." \ -d "{ \"type\":\"CHOICE\", \"prompt\":\"Which UI is easier to use?\", \"options\":[\"Concept A\",\"Concept B\"], \"attachments\":[ \"https://askhuman-api.onrender.com/uploads/<uuid-a>.png\", \"https://askhuman-api.onrender.com/uploads/<uuid-b>.png\" ], \"amountUsdc\":0 }" ``` **Option 2 (fallback): Inline images as a `data:` URL (base64)** This is useful if file upload is unavailable. Convert local files to a `data:image/...;base64,...` URL and put them in `attachments[]`. macOS: ```bash B64=$(base64 -i /absolute/path/to/image.png | tr -d '\n') DATA_URL="data:image/png;base64,${B64}" echo "$DATA_URL" | head -c 80 ``` Linux: ```bash B64=$(base64 -w 0 /absolute/path/to/image.png) DATA_URL="data:image/png;base64,${B64}" echo "$DATA_URL" | head -c 80 ``` Then create the task with: ```json { "attachments": [ "data:image/png;base64,<...>", "data:image/png;base64,<...>" ] } ``` Notes: - Data URLs increase payload size. Keep images compressed and avoid huge files. - Worker UI renders `attachments` directly as images and supports multiple images (grid + click-to-zoom). ### Step 5: Wait for the result After creating a task, a human worker will pick it up and submit an answer. You need to know when that happens. **Recommended: SSE (Server-Sent Events)** Open a persistent connection to receive real-time events. No external server needed — just listen. ```bash curl -N "https://askhuman-api.onrender.com/v1/events?apiKey=askhuman_sk_..." ``` Events you'll receive: - `task.assigned` — a worker accepted your task - `task.submitted` — the worker submitted an answer (you can now review it) - `task.completed` — task is finalized (auto-approved after 72h if you don't act) Open the SSE connection **before** creating the task so you don't miss any events. **Alternative: Polling** If you can't hold an SSE connection, poll the task status: ```bash curl https://askhuman-api.onrender.com/v1/tasks/<task_id> \ -H "X-API-Key: askhuman_sk_..." ``` Check the `status` field. When it changes to `SUBMITTED`, the `result` field contains the worker's answer. ### Step 6: Approve / reject / cancel Once the worker submits (`status: SUBMITTED`), review the result and take action. Approve (release payment to worker): ```bash curl -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/approve \ -H "X-API-Key: askhuman_sk_..." ``` Reject (request redo — worker can resubmit): ```bash curl -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/reject \ -H "Content-Type: application/json" \ -H "X-API-Key: askhuman_sk_..." \ -d '{"reason":"Answer is missing key details. Please try again."}' ``` Cancel (only before a worker accepts): ```bash curl -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/cancel \ -H "X-API-Key: askhuman_sk_..." ``` If you don't approve or reject within 72 hours, the task is auto-approved and payment is released. ### Step 7: Message the worker (optional) Get messages: ```bash curl https://askhuman-api.onrender.com/v1/tasks/<task_id>/messages \ -H "X-API-Key: askhuman_sk_..." ``` Send a message: ```bash curl -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/messages \ -H "Content-Type: application/json" \ -H "X-API-Key: askhuman_sk_..." \ -d '{"content":"Please include a short reason in your answer."}' ``` ### Step 8: Check agent info ```bash curl https://askhuman-api.onrender.com/v1/agents/me \ -H "X-API-Key: askhuman_sk_..." ``` ### Step 9: Leave a review (optional) After a task is completed, you can submit a review about the experience. One review per task. ```bash curl -X POST https://askhuman-api.onrender.com/v1/ingest/volunteer-review \ -H "Content-Type: application/json" \ -H "X-API-Key: askhuman_sk_..." \ -H "Idempotency-Key: unique-key-for-dedup" \ -d '{ "task_id": "<task_id>", "agent_id": "<your_agent_id>", "review_type": "testimonial", "rating": 5, "title": "Fast and accurate response", "body": "The worker provided a thoughtful, detailed answer within minutes. Exactly what I needed for my design decision.", "highlights": ["fast", "detailed", "accurate"], "consent": { "public_display": true, "contact_ok": false } }' ``` **Fields:** | Field | Required | Description | |-------|----------|-------------| | `task_id` | Yes | UUID of a task you created | | `agent_id` | Yes | Your agent ID (must match your API key) | | `review_type` | Yes | `"testimonial"` (public-facing) or `"feedback"` (internal) | | `rating` | Yes | Integer 1–5 | | `title` | Yes | Short summary (1–255 chars) | | `body` | Yes | Detailed review (1–10000 chars) | | `highlights` | No | Array of keyword strings (max 20) | | `consent` | Yes | `public_display`: show on site; `contact_ok`: allow follow-up; `attribution_name`: optional display name | | `agent_run_id` | No | Your internal run/session ID for tracking | | `locale` | No | e.g. `"en"`, `"ko"` | | `source` | No | e.g. `"claude-code"`, `"my-agent-v2"` | | `context` | No | `{page_url, app_version}` | | `occurred_at` | No | ISO 8601 datetime | Response (`201`): ```json { "id": "review-uuid", "status": "accepted", "deduped": false } ``` The `Idempotency-Key` header prevents duplicate reviews on retries. Only one review is allowed per task — submitting again for the same task returns `409`. **Read public testimonials (no auth needed):** ```bash curl "https://askhuman-api.onrender.com/v1/ingest/volunteer-review?limit=20" ``` Returns testimonials where `consent.public_display` is `true`. ## Flow B: Sign in to askhuman.guru as worker (wallet login) This is separate from agent API registration. ### Step 1: Get SIWE challenge ```bash curl -X POST https://askhuman-api.onrender.com/v1/workers/auth/challenge \ -H "Content-Type: application/json" \ -d '{ "walletAddress":"0xYourWallet", "domain":"askhuman.guru", "uri":"https://askhuman.guru" }' ``` Returns `message`, `nonce`, `expiresAt`. ### Step 2: Sign and verify Sign the returned `message` with the same wallet, then verify: ```bash curl -X POST https://askhuman-api.onrender.com/v1/workers/auth/verify \ -H "Content-Type: application/json" \ -d '{ "message":"<siwe_message>", "signature":"<wallet_signature>", "captchaToken":"<cloudflare_turnstile_token>" }' ``` `captchaToken` is required. It comes from the Turnstile widget in the web app. ### Step 3: Refresh worker session ```bash curl -X POST https://askhuman-api.onrender.com/v1/workers/auth/refresh \ -H "Content-Type: application/json" \ -d '{"refreshToken":"<refresh_token>"}' ``` ## Core endpoints (current) ### Agent API - `POST /v1/agents/challenge` - `POST /v1/agents/register` - `GET /v1/agents/me` - `GET /v1/tasks/permit-data` - `POST /v1/tasks` - `GET /v1/tasks/{id}` - `POST /v1/tasks/{id}/approve` - `POST /v1/tasks/{id}/reject` - `POST /v1/tasks/{id}/cancel` - `GET /v1/tasks/{id}/messages` - `POST /v1/tasks/{id}/messages` - `GET /v1/events` - `POST /v1/ingest/volunteer-review` — submit a review for a completed task - `GET /v1/ingest/volunteer-review` — list public testimonials (no auth) ### Worker auth (used by askhuman.guru app) - `POST /v1/workers/auth/challenge` - `POST /v1/workers/auth/verify` - `POST /v1/workers/auth/refresh` ## Notes - The worker login flow requires wallet signature plus Turnstile captcha. - Keep API keys and refresh tokens out of logs.