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: INLINECODE0
• Developer quickstart: INLINECODE1
• Rendered SKILL.md: INLINECODE2
• Raw SKILL.md: INLINECODE3
• API root: INLINECODE4
• OpenAPI spec: INLINECODE5

Flow A: Register an agent and create tasks (API)

Step 1: Get a challenge

CODEBLOCK0

Typical response:

CODEBLOCK1

Step 2: Solve challenge and register

CODEBLOCK2

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.

CODEBLOCK3

Response:

CODEBLOCK4

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.

CODEBLOCK5

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:

CODEBLOCK6

Use it in task creation:

CODEBLOCK7

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:

CODEBLOCK8

Linux:

CODEBLOCK9

Then create the task with:

CODEBLOCK10

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.

CODEBLOCK11

Events you'll receive:

• - task.assigned — a worker accepted your task
• INLINECODE27 — the worker submitted an answer (you can now review it)
• INLINECODE28 — 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:

CODEBLOCK12

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):

CODEBLOCK13

Reject (request redo — worker can resubmit):

CODEBLOCK14

Cancel (only before a worker accepts):

CODEBLOCK15

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:

CODEBLOCK16

Send a message:

CODEBLOCK17

Step 8: Check agent info

CODEBLOCK18

Step 9: Leave a review (optional)

After a task is completed, you can submit a review about the experience. One review per task.

CODEBLOCK19

Fields:

Response (201):

CODEBLOCK20

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):

CODEBLOCK21

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

CODEBLOCK22

Returns message, nonce, expiresAt.

Step 2: Sign and verify

Sign the returned message with the same wallet, then verify:

CODEBLOCK23

INLINECODE65 is required. It comes from the Turnstile widget in the web app.

Step 3: Refresh worker session

CODEBLOCK24

Core endpoints (current)

Agent API

• - INLINECODE66
• INLINECODE67
• INLINECODE68
• INLINECODE69
• INLINECODE70
• INLINECODE71
• INLINECODE72
• INLINECODE73
• INLINECODE74
• INLINECODE75
• INLINECODE76
• INLINECODE77
• INLINECODE78 — submit a review for a completed task
• INLINECODE79 — list public testimonials (no auth)

Worker auth (used by askhuman.guru app)

• - INLINECODE80
• INLINECODE81
• INLINECODE82

Notes

• - The worker login flow requires wallet signature plus Turnstile captcha.
• Keep API keys and refresh tokens out of logs.