Submit and retrieve hCaptcha tasks with curl

Inspect the raw customer API with curl, keep credentials in headers, and distinguish pending jobs, task failures, and HTTP problems.

Use curl to inspect the contract

A small curl request is useful when separating an API problem from an SDK or application problem. Prepare a customer API key in your shell environment and a request file containing the correct task type, sitekey, and page URL. Use a protected local environment rather than pasting real credentials into shared terminal transcripts.

{
  "type": "hcaptcha_token",
  "sitekey": "YOUR_SITEKEY",
  "url": "https://your-site.example/login",
  "hold": 30
}

Save this as task.json, replacing only the public integration values. Your account key belongs in the Authorization header, not in this file’s sitekey field.

Create once and keep the identifier

curl --max-time 45 --silent --show-error --include \
  https://api.easycaptcha.to/v1/task \
  -H "Authorization: Bearer ${EASYCAPTCHA_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @task.json

--include lets you inspect the actual HTTP status and content type alongside the body. A successful creation can still return pending work. Save the returned task_id and retrieve it with a GET to /v1/task/{task_id}; do not repeat the creation request simply because no token was immediately returned.

Read status and body together

HTTP problems use the documented Problem Details envelope. A task snapshot with status: "failed" carries an embedded task error. These are different layers: a successful lookup means the lookup succeeded, not that the job produced a usable result.

Use the API reference to interpret statuses and result fields. Keep a request ID when reporting a transport or gateway problem, and the task ID when investigating accepted work. Redact the Authorization header and any proxy password from saved output.

A curl timeout can happen after the server accepted the request. Avoid a shell retry flag that retries creation automatically. For a known ID, a repeated lookup is a different operation. The recovery guide explains what to retain, and long polling explains how to choose a wait interval that fits your HTTP deadline.