# Nativecheck: full guide for AI agents

Native speakers verify machine (LLM) translations. Reviews take minutes to hours, so the flow is asynchronous and fire-and-forget.

Nativecheck = native speakers verify machine translations; reviews take minutes to hours, so it is asynchronous. 1) Collect ALL texts you need checked and POST /api/v1/quotes once (requested_by: "agent", agent: your name; items: target_lang + content as text, html or a JSON object; optional ref, source, context, doubt 0-100, doubt_note). 2) Show summary_for_human (price range + ETA) to your human and ask for approval. 3) POST /api/v1/orders {quote_id} with an Idempotency-Key header. Save order_id + check_after in memory, tell the human the ETA, and follow wait_plan: start a long-running background task/timer that waits until check_after, then polls GET /api/v1/orders/{id} every 60 s. 4) When ready=true, GET /api/v1/orders/{id}/delivery and replace your texts by ref. 5) POST /api/v1/orders/{id}/ack. The human also gets an in-app/push notification when ready. Keep placeholders like {name}, %s and ⟦1⟧ unchanged. Prices are coins (1 coin = $0.01).

## 0. Get access
The human creates an API key at https://nativecheck.data-clerk.com/wallet (optional daily/total spending caps) and tops up coins there (1 coin = $0.01).
Send it as `Authorization: Bearer nck_…` on every call. Every response, including errors, has `how_to` and `next`.

## 1. Quote (no charge)
```
POST https://nativecheck.data-clerk.com/api/v1/quotes
{
  "requested_by": "agent", "agent": "your-agent-name",
  "reviewers": 2,
  "context": "Website for tea beginners, friendly tone",
  "doubt": 30,
  "items": [
    {"ref": "locales/de.json", "target_lang": "de", "source_lang": "en", "content": {"ui": {"h1": "Alle Tees erklärt"}}},
    {"ref": "about.fr.html", "target_lang": "fr", "content": "<p>Le thé <b>vert</b> est frais.</p>", "doubt_note": "unsure about tea terms"},
    {"ref": "blog/matcha.txt", "target_lang": "es", "content": "El matcha se bate con agua."}
  ]
}
```
- `content`: plain text, HTML (tags are protected) or a JSON object (every string value is checked, keys kept). `format` is auto-detected.
- `ref`: your own id; the delivery returns texts by ref.
- `doubt` (0–100) / `doubt_note`: how unsure you are. It only changes the price range; natives always read everything.
- Response `quote`: `quote_id`, `price_min`/`price_max` (coins), `hold`, `eta`, `enough_balance`, `summary_for_human`.

**Show `summary_for_human` to your human and ask for approval before ordering.**

## 2. Order
```
POST https://nativecheck.data-clerk.com/api/v1/orders
Idempotency-Key: any-unique-string
{"quote_id": "…"}
```
Returns `order_id`, `check_after`, `ready_by`, `message_for_human` and `wait_plan`.
Follow `wait_plan`: start a long-running background task or timer that waits until `check_after`, then polls every 60 s. It includes a ready shell loop:
```
sleep N; until curl -sf -H "Authorization: Bearer $NATIVECHECK_KEY" https://nativecheck.data-clerk.com/api/v1/orders/ID | grep -q '"ready":true'; do sleep 60; done
```
If you can't run background tasks, save `order_id` and `check_after` to memory. The human also gets an in-app/push notification when it's ready.

## 3. Check
`GET https://nativecheck.data-clerk.com/api/v1/orders/{id}` → `ready`, `progress`, `retry_after` (also as a Retry-After header).

## 4. Collect
`GET https://nativecheck.data-clerk.com/api/v1/orders/{id}/delivery` → `items[]` with `ref`, `final` (text/HTML) or `final_json`, changed segments, and provenance per segment (pseudonymous reviewer ids, method, timestamps, SHA-256 of original and final). 409 while not ready.

## 5. Ack
`POST https://nativecheck.data-clerk.com/api/v1/orders/{id}/ack`. Texts are deleted after the retention period; provenance hashes are kept.

## Other endpoints
- `GET https://nativecheck.data-clerk.com/api/v1`: endpoint index
- `GET https://nativecheck.data-clerk.com/api/v1/wallet`: balance and top-up link
- `GET https://nativecheck.data-clerk.com/api/v1/languages`: languages and number of native reviewers
- `GET https://nativecheck.data-clerk.com/openapi.json`: OpenAPI 3.1

## MCP
Streamable HTTP at `https://nativecheck.data-clerk.com/mcp`, same Bearer key. Server card: `https://nativecheck.data-clerk.com/.well-known/mcp.json`.
```
claude mcp add --transport http nativecheck https://nativecheck.data-clerk.com/mcp --header "Authorization: Bearer nck_YOUR_KEY"
```
Tools: quote_review → place_order → check_order → collect_order → ack_order, plus balance and languages.

## Errors
401 bad key · 402 insufficient balance or key cap (top up at https://nativecheck.data-clerk.com/wallet) · 409 not ready · 410 deleted after retention · 422 invalid input.

## Rules for content
Keep placeholders such as `{name}`, `{{count}}`, `%s`, `%1$d` and HTML tags; natives cannot change them.

## Languages
`en` English, `de` Deutsch, `fr` Français, `es` Español, `it` Italiano, `pt` Português, `nl` Nederlands, `pl` Polski, `uk` Українська, `cs` Čeština, `sk` Slovenčina, `hr` Hrvatski, `bg` Български, `sv` Svenska, `da` Dansk, `nb` Norsk bokmål, `fi` Suomi, `zh` 简体中文, `ja` 日本語, `ko` 한국어, `tr` Türkçe, `ro` Română, `hu` Magyar, `el` Ελληνικά
## Related

- [Coffee Types](https://coffeetypes.data-clerk.com/): visual guide to coffee drinks in 29 languages ([llms.txt](https://coffeetypes.data-clerk.com/llms.txt))
- [Tea Types](https://teatypes.data-clerk.com/): visual guide to teas with brewing data in 18 languages ([llms.txt](https://teatypes.data-clerk.com/llms.txt))
- [Data Clerk](https://data-clerk.com/): the studio behind Nativecheck ([llms.txt](https://data-clerk.com/llms.txt))