The NoneCap hCaptcha API.

Quickstart

1. Sign in to the dashboard and mint an API key (nc_live_…).
2. POST a solve to /v1/solves. Add ?wait=N (1-90 s) to block up to N seconds and return as soon as the solve reaches a terminal state. If the solve is still in flight when that window closes you get a 202 with a null token, so poll GET /v1/solves/{id} until it's terminal.
3. Inject the returned P1_ token into the target form's h-captcha-response field and submit it with the solve's user_agent as your User-Agent header. Some sites refuse a token sent from a different browser version.
4. Report the tokens your target refuses to /v1/feedback — send the solve_id with an outcome of rejected. A token can pass hCaptcha and still be refused by your target, and this is the only signal that shows us that. Reporting accepted tokens too is optional and sharpens the read. Feedback reference

Authentication

You mint API keys in the dashboard. Format: nc_live_ + 32 base64url characters. Send it on every request:

Authorization: Bearer nc_live_a8f2K9...

Errors

• 401 unauthorized: missing, malformed, revoked, or unknown key.
• 402 insufficient_credits: valid key but balance < 1; only raised on calls that consume credits.
• 402 key_credit_limit_exceeded: the key reached its optional per-key credit limit; raise or reset it on the Keys page.

Sign up in the dashboard to mint a key and claim 1,300 free credits. A future nc_test_ prefix is reserved for test-mode keys.

Errors

Every non-2xx response follows the same envelope:

{
  "error": {
    "code":    "insufficient_credits",
    "message": "Your account has no credits remaining. Top up at https://dashboard.nonecap.com/billing.",
    "param":   null,
    "request_id": "9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f"
  }
}

param names the offending request field for validation errors; otherwise null. request_id (also the X-Request-Id response header) is the id to quote to support.

HTTP status codes

Solve-failure codes

These ride in Solve.error.code on a terminal, non-solved solve. status is failed, cancelled, or expired. The request succeeded; the solve didn't produce a token, and nothing was charged. The message differs by whether you supplied a proxy: the first sentence below is the proxied wording, the second the proxyless one.

Solve-failure reasons

error.reason is a typed sub-reason within error.code, set when the solver knows more than the code says; null otherwise. error.retryable says whether re-submitting the same request unchanged can succeed.

Versioning

This is v1. Breaking changes will ship under v2 with at least 12 months of v1 support.

Resource shapes are additive within a major version: new optional fields can appear at any time. Clients should ignore unknown fields rather than treating them as an error.

Pagination

List endpoints use cursor-based pagination. The cursor is the id of the last item you received; pass it as starting_after on the next request.

• limit: 1-100, default 20.
• starting_after: a solve_… id (exclusive cursor).
• Responses carry has_more: boolean. There is no separate cursor field: read the last item's id.

Switching from NopeCHA

Code written against NopeCHA's hCaptcha Token API runs here: use the base URL https://api.nonecap.com/compat/nopecha with your NoneCap API key (header, key body field or key query parameter). It accepts /token with type: "hcaptcha" and /v1/token/hcaptcha; other types are refused. Solves bill, rate-limit and appear in your dashboard exactly like POST /v1/solves. cookie and useragent are accepted but ignored, so a site that binds the token to a cookie session may refuse it. Balance and status are not aliased: use the dashboard or GET /v1/me.

curl https://api.nonecap.com/compat/nopecha/token \
  -H "Authorization: Bearer nc_live_••••" \
  -H "Content-Type: application/json" \
  -d '{"type": "hcaptcha", "sitekey": "…", "url": "https://example.com/login"}'
# → {"data": "solve_…"}; then GET /compat/nopecha/token?id=solve_… until it returns {"data": "P1_…"}

NopeCHA's hCaptcha recognition calls run on the same base URL: POST / with type hcaptcha or hcaptcha_area_select (their SDKs' recognize_hcaptcha and recognize_hcaptcha_area_select), and POST /v1/recognition/hcaptcha with a data challenge object. The answer is ready when the submit returns, so the first poll returns it. New code can call POST /v1/recognize directly and skip the poll.

curl https://api.nonecap.com/compat/nopecha/ \
  -H "Authorization: Bearer nc_live_••••" \
  -H "Content-Type: application/json" \
  -d '{"type": "hcaptcha", "task": "Please click each image containing a bicycle", "image_data": ["…"]}'
# → {"data": "rec_…"}; GET /compat/nopecha/?id=rec_… returns {"data": [true, false, …]} at once

The solve object

A solve represents one captcha-solving job: its parameters, the worker that picked it up, the resulting token, and how much it cost you.

Attributes

Lifecycle

pending → solving → solved
                  → failed
                  → expired     (exceeded time budget / reclaimed)

pending | solving → cancelled   (via DELETE)

Records are purged after a 30-day retention window; after that GET /v1/solves/{id} returns 404. That retention is separate from the expired status above.

Captcha types

Create a solve

Submit a new captcha solve. You're charged only when a solve succeeds (the amount is metered per round and reported as credits_charged); failed, cancelled, and expired solves are never charged. Submitting requires a balance of at least 1 credit.

Body parameters

Query parameters

Responses

Retrieve a solve

Fetch the current state of a solve by id. With ?wait=N (1-90 s), the call blocks until the solve reaches a terminal state or the wait expires.

Path parameters

Query parameters

Responses

List solves

Cursor-paginated history of solves for the authenticated account. Newest first.

Query parameters

Response carries has_more: boolean. There is no separate cursor field. The cursor is the id of the last item in data.

Cancel a solve

Cancel a pending or solving solve. A cancelled solve is never charged.

Path parameters

Responses

Account & balance

Returns the authenticated account plus the current credit balance. Useful for showing balance in your own dashboard or as a pre-flight before a batch.

Response

Report feedback

Report the tokens your target rejected, so we can see how they actually performed and catch regressions early. Reporting accepted ones as well is optional. This is the batch endpoint: buffer your verdicts and flush up to 500 at once. There's no extra charge and no new key or scope, since it's gated on the same solve scope that created the solves, so your existing API key works unchanged. You can only report your own solves.

Body parameters

Feedback item

Rules

• You can report your own solves only. A foreign or unknown id resolves to a per-item not_eligible.
• Only a solve that reached solved is reportable; anything else is not_eligible.
• The first report must land within 30 days of the solve. A late first report is expired_window, but corrections to an already-reported solve are not age-gated.
• Reports are idempotent and last-write-wins. Reporting the same solve_id again overwrites the mutable fields (status: updated); re-sending an identical value does nothing (status: unchanged). The first reported outcome stays immutable server-side and report_count bumps only on a real change, so verdict flips stay auditable.

Two response shapes

This batch endpoint returns the batch envelope, { object: "feedback_batch", recorded, updated, unchanged, failed, results }, where each results entry has a status of recorded, updated, unchanged or error, and a failed item nests a bare { code, message, param } without the error wrapper. The single-item alias below returns the feedback resource directly, or the standard { error: { code, message, param } } envelope on failure. Handle both.

Responses

Per-item error.code values inside a 200 batch are validation_error (bad field), not_eligible (unknown / foreign / not-solved id), or expired_window (first report past the 30-day window).

Report one solve

Convenience alias for reporting a single solve. It runs the same validation and upsert path as one Report feedback batch item, and is meant for low-volume callers and interactive testing. The solve_id comes from the path, so the body is just the item fields (no feedback wrapper). High-volume integrations should use the batch endpoint above.

Body parameters

The rules match the batch endpoint: your own solves only, only solves that reached solved, a first report within 30 days, and idempotent last-write-wins.

Responses

Recognize a challenge

For callers who run their own browser or extension and only need the answer: send one hCaptcha challenge's images and instruction, get back which tiles to click, where to click, or where to drop each piece, in the same response. There is no token and no polling; your own client clicks and submits. The request and answer fields are the ones NopeCHA's recognition API uses, so an integration written for it needs only the new URL and key.

Use an API key with the solve scope. Each answered call costs a flat 5 credits, whatever the challenge type, and credits_charged in the response says what it cost. The charge is final once the answer is returned, however the challenge ends. A puzzle we do not support yet is refused with recognition_failed and not charged: load a fresh challenge and send that. Your calls and the credits they used appear on the dashboard's Analytics page.

Body: the simple form

Body: the full form

The answer

• id: this recognition, for the outcome report.
• Grid, simple form: data is one boolean per tile, true = click it. Full form: one array of up to 9 booleans per page.
• Area select: data is { x, y, w, h } in percent of the image, with w and h 0: click at x, y. When the instruction asks for more than one click, points lists them all. Full form: one box per task, and points per task.
• Drag: data holds, per task, where each piece goes: entity_id and its box (x, y = the piece's top-left, w, h = its size), in percent of the image. Drag its centre to x + w/2, y + h/2. Pieces to leave in place are not listed.
• credits_charged: what this call cost.

Limits

Per account, across all its API keys: as many calls in flight as its concurrency limit, and 60 calls a minute per unit of that limit. Over either you get 429 with Retry-After; nothing is charged.

Responses

Report a recognition outcome

Optional. Tell us how the challenge ended after you applied the answer; we use it to track accuracy. It does not change billing: no credits are refunded for any result, so refunded_credits is always 0. The first report for an id is the one kept. An id that is not one of your recognitions is 404 not_found.