API reference

Submit a task

Create one paid task. The response can wait for completion using hold.

Authentication

API key. Enterprise token tasks require explicit account whitelisting.

Request body

{
  "type": "hcaptcha_token",
  "sitekey": "YOUR_SITEKEY",
  "url": "https://example.com",
  "hold": 30
}

Response

202 application/json when queued or running after hold. 200 application/json when completed or failed during hold. Both return the Task body below.

{
  "task_id": "task_01m40t5ag0e008000000000001",
  "type": "hcaptcha_token",
  "status": "queued",
  "created_at": "2026-10-03T12:00:00Z",
  "completed_at": null,
  "expires_at": null,
  "result": null,
  "error": null
}

A task continues when hold ends or the client disconnects. Do not automatically repeat this POST after an ambiguous timeout.

The default JSON body limit is 4 MiB. Unknown types and invalid values are rejected before admission.

Recognition task fields, image inputs, task counts, and drag entities are validated before the task is charged or queued.

Errors

invalid_request, invalid_credentials, insufficient_balance, forbidden, account_suspended, payload_too_large, rate_limited.

Get a task

Read an immediate task snapshot. This endpoint does not wait for completion.

Authentication

API key belonging to the task's account.

Path and query parameters

Request body

No request body.

Response

200 application/json. A failed task is also returned with HTTP 200 and an embedded problem in error.

{
  "task_id": "task_01m40t5ag0e008000000000001",
  "type": "hcaptcha_token",
  "status": "completed",
  "created_at": "2026-10-03T12:00:00Z",
  "completed_at": "2026-10-03T12:00:10Z",
  "expires_at": "2026-10-03T12:05:10Z",
  "result": {
    "token": "HCAPTCHA_TOKEN"
  },
  "error": null
}

The default result retention window is five minutes after completion. Save the result promptly. An expired, unknown or non-owned task returns task_not_found.

Errors

invalid_request, invalid_credentials, task_not_found, account_suspended, rate_limited.

Report a task outcome

Report whether an owned, completed and still-retained task succeeded in use. Feedback is used to improve AI performance.

Authentication

API key belonging to the task's account.

Path and query parameters

Request body

{
  "success": true
}

Response

204 No Content. No response body.

Repeating identical feedback is a no-op. Conflicting feedback returns 409.

Errors

invalid_request, invalid_credentials, task_not_found, conflict, rate_limited.

Get recent task history

Get your latest 50 admitted tasks from the past seven days, newest first. No request body or query parameters. History contains summaries only, with no payloads, solutions or tokens.

Authentication

API key.

Request body

No request body.

Response

200 application/json.

{
  "currency": "USD",
  "items": [
    {
      "task_id": "task_01m40t5ag0e008000000000001",
      "type": "hcaptcha_recognition",
      "status": "completed",
      "cost_microcents": "20000",
      "created_at": "2026-10-04T12:00:00Z",
      "completed_at": "2026-10-04T12:00:02Z"
    }
  ]
}

Entries are retained for at most seven days and may disappear sooner when newer tasks exceed the 50-entry limit. Financial records and aggregate usage have separate retention.

Errors

invalid_credentials, account_suspended, rate_limited, service_unavailable.

Get your task rates

Read your current effective prices, including custom pricing and mode multipliers. No request body or query parameters.

Authentication

API key.

Request body

No request body.

Response

200 application/json.

{
  "currency": "USD",
  "rates": {
    "hcaptcha_recognition": {
      "standard_microcents": "10000"
    },
    "hcaptcha_token": {
      "standard_microcents": "200000"
    },
    "hcaptcha_enterprise_token": {
      "standard_microcents": "500000"
    }
  },
  "burst_multiplier": 1.5,
  "fast_multiplier": 1.2
}

1 USD = 100,000,000 microcents. Recognition groups contain nine binary tiles or one area/drag image.

For multiple groups, multiply the standard price by the group count and selected mode multiplier, then round upward once.

Rates apply to new requests. Existing charges retain their original prices.

Errors

invalid_credentials, account_suspended, rate_limited, service_unavailable.

Get available balance

Read the account's available USD credit.

Authentication

API key.

Request body

No request body.

Response

200 application/json.

{
  "currency": "USD",
  "balance_microcents": "100000000"
}

Errors

invalid_credentials, account_suspended, rate_limited.

List public extensions

List extensions available to the caller. Anonymous callers see only public extensions; a valid session applies account visibility and permission rules.

Authentication

Optional session. Anonymous callers see only public extensions; a valid session applies account visibility and permission rules.

Path and query parameters

Request body

No request body.

Response

200 application/json. A page containing items and next_cursor (null when there are no more results).

Errors

invalid_request, rate_limited.

Get the latest extension version

Get metadata and a temporary download link for the latest stable release.

Authentication

None.

Path and query parameters

Request body

No request body.

Response

200 application/json. The response describes the selected version and its download link.

Errors

invalid_request, not_found, rate_limited.

Get available extension releases

Get the latest stable release and the newest prerelease only when it is newer than stable. Each includes a temporary download link.

Authentication

None.

Path and query parameters

Request body

No request body.

Response

200 application/json. Either release can be null. An extension with no available releases returns both as null.

Errors

invalid_request, not_found, rate_limited.

Get an extension release

Get a specific release and a fresh signed download link. Unavailable releases return 404.

Authentication

None.

Path and query parameters

Request body

No request body.

Response

200 application/json. A Version object with a temporary signed download link.

Errors

invalid_request, not_found, rate_limited.

hCaptcha recognition payload

Send {"type":"hcaptcha_recognition","task":{…}} toPOST /v1/task. The task field is the challenge object itself. You may also include an optional top-level sitekeystring for site-specific challenge and outcome attribution. Include these challenge fields:

A media input is a nonempty data:image/png;base64,… ordata:video/webm;base64,… URI containing valid base64 data. HTTP(S) and other remote media URLs are rejected. This applies to task images, videos, drag entities, and question examples.

Additional fields inside the challenge are preserved. Image arrays in place of the challenge object and text_free_entry are rejected. Validation runs before charging or queue admission.

Recognition is billed per challenge group: nine binary tiles, one area-selection image, or one drag/drop image. Requests with two or three groups cost twice or three times the base price. Burst and fast multipliers apply to the total, with fractional microcents rounded upward once.

Recognition results are objects keyed by the original task_key. Binary images are processed in consecutive groups of nine, then each tile maps to a boolean: true selects that tile.

Area selection maps each task key to an array of{entity_coords, entity_name} objects. Points use[x, y]; rectangles use [x, y, x+w, y+h]. The name is a zero-based number in click order, starting again for each image.

Drag/drop maps each task key to one placement per entity, in task entity order. Each placement has entity_coords: [x, y] andentity_name equal to the original entity_id. Entities the worker did not move retain their original coords.

Worker coordinates and dimensions use absolute pixels inside the image, video, or canvas. Empty area selections return []. A failed worker group returnsnull under each affected task key.

Response models

Extension version responses use the definition below.