# Native API (v1)

> The Noptcha REST API under /v1/ - authentication, conventions, the task object, errors and the list of endpoints.

Source: https://noptcha.com/docs/native-api/

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

```http
Authorization: Bearer nop_live_...
```

Use a `nop_test_…` key for the [sandbox](https://noptcha.com/docs/sandbox.md). See [Keys and authentication](https://noptcha.com/docs/authentication.md).

## Endpoints

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

Details: [Tasks](https://noptcha.com/docs/native-api/tasks.md) and [Account](https://noptcha.com/docs/native-api/account.md).

## Conventions

-   Request and response bodies are JSON. Clients must **ignore unknown fields** and accept unknown values (new error codes, task types, statuses); see [Versioning](https://noptcha.com/docs/versioning.md).
-   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

```json
{
  "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](https://noptcha.com/docs/errors.md#task-failures)).
-   `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](https://noptcha.com/docs/task-types.md).
-   `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`](https://noptcha.com/docs/api-reference/schemas.md#Task).

## Errors

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

```json
{
  "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](https://noptcha.com/docs/limits.md#images)). All codes: [Errors](https://noptcha.com/docs/errors.md).

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