# NI — Human Judgment API

You can submit work to real people via the NI API. Base URL: `https://ni.dev/api`

If you are an AI agent that is stuck, start with **Escalate** — it hands the problem to a vetted human expert and webhooks you the result.

## What you can do

### Escalate (human expert takes over)
```
POST /api/bounties
Authorization: Bearer $NI_API_KEY
{
  "action_type": "create",
  "title": "app.example.com points at the dead load balancer",
  "description": "Evidence (scrubbed): ...\n\nDone when: curl -sf https://app.example.com/health returns 200",
  "domain": "coding",
  "pay_cents": 2500,
  "min_accuracy": 0.85,
  "visibility": "private",
  "external_ref": "TICKET-482",
  "callback_url": "https://agent.example.com/ni/webhook"
}
```

The bounty is escrowed (pay + 20% fee — the same stack every NI work stream carries, funding worker UBI, quality assurance, and moderation) from your NI balance.

Fund your balance without a human: `POST /api/payments/x402` with `{"amount_cents": 10000, "purpose": "deposit"}` (Bearer key) returns an x402 payment request (USDC on Base); pay it, then `POST /api/payments/x402/verify` with `{"payment_id", "tx_hash"}` — verification credits your balance idempotently (a tx hash can credit exactly one deposit, ever). Card fallback: `POST /api/payments/checkout` with `purpose: "deposit"` (Bearer key) returns a Stripe checkout URL; the webhook credits on completion. `external_ref` makes creation idempotent per ticket — re-posting returns the live bounty instead of double-escrowing. `visibility: "private"` restricts claiming to workers you vouch for; `min_accuracy` and `min_tier` gate on the worker's tracked record and verification level. Include scrubbed evidence and a machine-checkable done-when in the description; experts submit plans — never ask for or send credentials. Lifecycle webhooks (`bounty.claimed`, `bounty.submitted` — carries the expert's change plan inline, `bounty.completed`, `bounty.cancelled`) POST to `callback_url`, HMAC-SHA256-signed in `X-NI-Signature` with the secret from `GET /api/webhook_secret`. Approve with `{"action_type": "approve", "bounty_id": "..."}` to release escrow. Human-readable overview: https://ni.dev/escalation

### Evaluate (A/B comparison)
```
POST /api/tasks/batch
{
  "type": "preference_ranking",
  "domain": "coding",
  "pay_per_task_cents": 25,
  "workers_per_task": 3,
  "pairs": [{"prompt": "Which is better?", "response_a": "...", "response_b": "..."}]
}
```

Optional batch fields: `"overflow": true` lets NI backfill with external crowd supply (e.g. Prolific) if NI workers haven't cleared the batch within ~2 hours — phone-tier batches only; demographic-targeted batches overflow too when the targeting maps to supplier screeners (age, gender, country, political), otherwise they stay internal-only; results are labeled `internal` vs `external` in batch status. `"quality_check_threshold": 70` enforces attention checks (pairs marked `"quality_check": true` with a `"known_answer"`).

### Evaluate (Review with custom labels)
```
POST /api/tasks/batch
{
  "type": "single_review",
  "domain": "safety",
  "pay_per_task_cents": 50,
  "workers_per_task": 3,
  "pairs": [{"prompt": "Is this safe?", "response_a": "content here", "response_b": "[\"safe\",\"unsafe\",\"needs review\"]"}]
}
```

### Ask (Poll)
```
POST /api/polls
{
  "title": "Which logo do you prefer?",
  "mode": "vote",
  "pay_per_response_cents": 10,
  "target_responses": 100,
  "questions": [{"question": "Which logo?", "question_type": "choice", "options": ["A", "B", "C"]}]
}
```

### Ask (Expert)
```
POST /api/polls
{
  "title": "What causes this crash?",
  "mode": "oracle",
  "domain": "coding",
  "min_skill_level": "expert",
  "pay_per_response_cents": 100,
  "target_responses": 3,
  "questions": [{"question": "What causes this crash?", "question_type": "text", "options": []}]
}
```

### Ask (Survey)
```
POST /api/polls
{
  "title": "What would you change about our product?",
  "mode": "survey",
  "pay_per_response_cents": 25,
  "target_responses": 50,
  "questions": [{"question": "What would you change?", "question_type": "text", "options": []}]
}
```

### Hire (One-off task)
```
POST /api/bounties
{"title": "Review our docs", "description": "...", "domain": "coding", "pay_cents": 500}
```

### Verify (Deepfake / Fact check / Oracle)
```
POST /api/verify
{"type": "deepfake", "content": "https://example.com/image.jpg", "votes": 5, "tier": "paid"}
```

Every verifier must cite evidence (a source URL or reasoning note). Results at `GET /api/verify/:public_id` include `receipts` (each verifier's stance + evidence), `verdict_language` (calibrated wording — panel opinion, not certification), and `panel_accuracy` (live accuracy on planted ground-truth checks, last 30 days). If the panel splits, the verdict enters `cross_examining`: each verifier's cited evidence is checked by fresh reviewers, refuted claims lose their vote's support, and each receipt carries its `claim_check` outcome — at no extra cost to you.

Fact-check panels can also rule `opinion` or `prediction` — "no fact to check" is a first-class verdict. Verified verdicts carry a right of reply: `POST /api/verify/:public_id/challenge` with `note` and/or `evidence_url` (one challenge per verdict, evidence required). The counter-claim and the verdict's supporting receipts all go to fresh checkers; an upheld challenge withdraws the verdict to uncertain/unverifiable — it never silently flips it.

Settle an argument: `POST /api/verify/:public_id/stake` with `name` + `position` puts parties publicly on record before the verdict (bragging rights only — NI never holds money); results appear in `stakes` with `right` per party.

`POST /api/verify` also accepts a screenshot instead of text/URL content: multipart `upload` (image ≤10MB) — the panel judges the image directly.

### Resolve (bet / market resolution)
```
POST /api/resolve
{"type": "fact_check", "content": "Did X happen before Y?", "votes": 5, "skill_level": "expert", "challenge_window_hours": 24, "webhook_url": "https://example.com/hook"}
```

Resolution-as-a-service for prediction markets and bet-settling apps: an evidence-backed human panel verdict with finality semantics. `GET /api/resolve/:id` is the authoritative state — `status`, `result`, `receipts`, and `final` (true once the challenge window closes unchallenged, or after a challenge resolves). Webhooks fire on `verdict`, `challenged`, and `final` (unsigned — treat as a doorbell and fetch the GET endpoint). NI is the referee, never the book: no stakes are held here.

### Vote (Election)
```
POST /api/elections
{
  "title": "Should we adopt a 4-day work week?",
  "options": ["Yes", "No", "Abstain"],
  "election_type": "simple",
  "min_verification": "world_id_orb",
  "closes_at": "2026-04-20T00:00:00Z",
  "pay_cents": 500
}
```

### Advertise
```
POST /api/sponsored
{"title": "Try our app", "content_type": "link", "content_url": "https://...", "pay_per_view_cents": 5, "target_views": 1000}
```

## Check results

- Batch: `GET /api/tasks/batch?id=BATCH_ID`
- Poll: `GET /api/polls?id=POLL_ID&results=true`
- Verification: `GET /api/verify/PUBLIC_ID`
- Leaderboard: `GET /api/leaderboard?domain=coding`

## Pricing
- Beginner: $0.25/task
- Skilled: $0.50/task
- Expert: $1.00/task
- 15% platform fee on all work

Always confirm cost with the user before submitting.