Native API (v1)

The native API is REST + JSON under https://api.noptcha.com/v1/. Compared with the compatibility API it can wait for a result in the same request, retries safely with idempotency keys, and reports errors with HTTP status codes.

Authentication

Authorization: Bearer nop_live_...

Use a nop_test_… key for the sandbox. See Keys and authentication.

Endpoints

Endpoint	What it does	Scope
`POST /v1/tasks`	Create a task, optionally wait for the result	`tasks:write`
`GET /v1/tasks/{id}`	Get a task, optionally long-poll with `?wait=`	`tasks:write`
`POST /v1/tasks/{id}/feedback`	Report whether the answer worked	`tasks:write`
`GET /v1/balance`	Balance	`balance:read`
`GET /v1/types`	Task types and prices for your organization	any valid key
`GET /v1/me`	The key itself: organization, scopes, restrictions, budget, limits	any valid key
`GET /v1/usage`	Usage and spending by hour or day	`usage:read`
`GET /v1/catalog`	Public task types and list prices	none

Details: Tasks and Account.

Conventions

Request and response bodies are JSON. Clients must ignore unknown fields and accept unknown values (new error codes, task types, statuses); see Versioning.
Every response carries Noptcha-Request-Id; include it when you contact support.
Times are RFC 3339 in UTC, always with exactly three fractional digits (milliseconds) and a Z suffix: 2026-11-05T08:00:00.120Z.
Money is a decimal string with 6 places plus a currency: {"amount": "0.000900", "currency": "USD"}.
IDs are strings. Task IDs are 53-bit integers written as strings (the compatibility API returns the same number as an integer).
An unknown path, or a known path with a method it does not support, is 404 not_found (not 405).

The task object

{
  "id": "7259140378796032",
  "type": "recaptcha.v2",
  "status": "solved",
  "params": { "website_url": "https://example.com/login", "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-" },
  "solution": { "token": "03AFcWeA…", "user_agent": "Mozilla/5.0 …" },
  "error": null,
  "cost": { "amount": "0.000900", "currency": "USD" },
  "created_at": "2026-11-05T08:00:00.123Z",
  "completed_at": "2026-11-05T08:00:07.456Z",
  "metadata": { "order": "A-17" }
}

(The amount above is illustrative, not a price.)

status is processing, solved or failed. A failed task has error: {code, message} and costs zero (task failure codes).
params are the parameters you sent, with secrets removed (proxy login and password; cookies where the type marks them sensitive) and long strings such as images replaced by "[N bytes]".
solution depends on the type: see its task type page.
metadata is returned as you sent it.
Tasks created with a test key have "sandbox": true.
A task can be read for 10 minutes after it completes.

Full schema: Task.

Errors

Errors are RFC 9457 problem details (application/problem+json) with a machine-readable code:

{
  "type": "https://noptcha.com/docs/errors/insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "code": "insufficient_balance",
  "detail": "Available $0.000300, task price $0.000900.",
  "request_id": "req_…"
}

422 invalid_params adds errors, a list of {pointer, message} where pointer is a JSON Pointer from the root of the request body (/params/website_key); problems with an image also carry a machine-readable reason (image_too_large, image_format, image_base64, image_empty; see Images). All codes: Errors.

429 and 503 responses carry Retry-After (seconds): wait that long before retrying.