# Token API

`POST https://api.ninetile.io/v1/solves` creates a solve. A successful solve returns a token and the user agent used. It does not guarantee acceptance by a target.

## Request fields

- `type` (required): `hcaptcha` or `hcaptcha_enterprise`.
- `sitekey` (required): the hCaptcha widget's UUID; reCAPTCHA keys are not supported.
- `url` (required): the HTTP or HTTPS page where the challenge appears; at most 2,048 characters.
- `rqdata` (optional): fresh request data when supplied by the page, at most 16,384 characters.
- `user_agent` (optional): browser user agent, at most 512 characters.
- `proxy` (optional): an HTTP(S) proxy string or object with `host`, `port`, `scheme`, `username`, and `password`. The proxy host must be public. Without it, the service uses its own proxy pool.

```sh
curl 'https://api.ninetile.io/v1/solves?wait=60' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"type":"hcaptcha","sitekey":"f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8","url":"https://example.com/"}'
```

Never paste a real API key or proxy password into shared examples. Sitekeys and URLs here are placeholders.

## Waiting and polling

`wait` is an optional whole number from 1 to 90 seconds on create or retrieve. Without it, creation returns HTTP 202 with a solve ID. With it, a completed solve returns HTTP 200; a solve still running returns 202. Use `GET /v1/solves/{id}?wait=60` to poll the same solve rather than creating repeated tasks.

Statuses are `pending`, `solving`, `solved`, `failed`, `cancelled`, and `expired`. A solved response contains `id`, `status`, `token`, `user_agent`, timestamps, and `charged_usd`. Running or failed solves have no token. A terminal failure includes `error.code`, `message`, `reason`, and `retryable`. Retry only when appropriate and create a fresh solve for a retry.

## Manage and report

- `GET /v1/solves`: newest-first list; supports `limit` (1–100), `starting_after`, `status`, and `type`.
- `DELETE /v1/solves/{id}`: cancel a running solve.
- `POST /v1/solves/{id}/feedback`: report one outcome.
- `POST /v1/feedback`: report up to 500 items in a `feedback` array with `solve_id`, `outcome` and optional `reason`. Outcomes: `accepted`, `rejected`, `unknown`, `unused`, `error`.

A solve reserves its price while in progress. Solved work is charged; failed, cancelled and expired solves release the reservation. The current displayed price is $0.75 per 1,000 solved tokens. Tokens are single-use and short-lived; stored tokens are cleared after seven days.

## Solve response fields

The object contains `id`, `object`, `type`, `status`, `sitekey`, `url`, `token`, `user_agent`, `error`, `charged_usd`, `created_at`, `started_at`, `finished_at`, `queue_ms` and `resolve_ms`. The token is present only after success, and a pending charge is not yet settled. Do not log tokens.

For feedback, the first report must arrive within 30 days of a successful solve. Optional `reason`, `context` and ISO 8601 `reported_at` fields supply context. Only the account owning a solved task can report it.

Canonical: https://ninetile.io/docs/token-api