Request a reCAPTCHA Enterprise token with cURL

• Have cURL and jq available in your shell.
• Set SOLVETHREE_API_KEY to your workspace API key. Run these commands server-side; keep the key out of browser code.
• Set SOLVETHREE_PROXY to the proxy URL you intend to use for solving and submitting the token.
• Set up an active reCAPTCHA site profile in the console for your workspace. Replace accounts.example.com and login in the example with your hostname and action.

Sending a hostname and action doesn't create a site profile. The profile must already be active before you request a solve.

# Set SOLVETHREE_API_KEY and SOLVETHREE_PROXY in your environment first.
# Replace the hostname and action with your active site profile.
jq -n \
  --arg proxy "$SOLVETHREE_PROXY" \
  --arg requestId "login-$(date +%s)-$$" \
  '{site:"accounts.example.com", action:"login", proxy:$proxy, requestId:$requestId}' \
| curl --fail-with-body --max-time 30 \
  'https://api.solvethree.com/v1/tasks?waitMs=15000' \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @-

The JSON body supplies site, action and a single proxy. Exactly one of proxy or proxyCandidates is required. Don't add type or url; omitting recaptchaType selects enterprise-v3.

The waitMs=15000 query parameter asks the creation request to wait up to 15 seconds. It belongs in the URL, not the JSON body. The cURL timeout is 30 seconds, leaving room beyond that server-side wait for network overhead. A task can still be nonterminal when the response arrives.

Check for an HTTP error before interpreting the body as a task response. Both commands use --fail-with-body; handle a failed HTTP request separately from a task whose status is failed.

A ready response has this shape. The values below are placeholders, not a token you can submit.

{
  "id": "example-task",
  "status": "ready",
  "solution": {
    "token": "EXAMPLE_TOKEN",
    "userAgent": "EXAMPLE_USER_AGENT",
    "secChUa": "EXAMPLE_CLIENT_HINTS"
  }
}

For a nonterminal response, set TASK_ID in your environment to its returned id, then retrieve it:

curl --fail-with-body --max-time 30 \
  "https://api.solvethree.com/v1/tasks/$TASK_ID?waitMs=15000" \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY"

This GET waits up to 15 seconds for a result, with a 30-second HTTP timeout. Without waitMs, GET returns without waiting. Repeat the GET only while the status is pending or solving, and set an overall deadline in your caller so the polling loop can't run indefinitely.

If the task fails, use its error details rather than assuming a credit problem. For example, site-unreachable calls for checking target reachability, not blindly resubmitting unchanged inputs.

Use solution.token in the target application's request. The task id is only for retrieving the task; it isn't the CAPTCHA token. Where the token belongs depends on the target's form or API, so there is no universal target-submission command.

Use the returned solution.userAgent and solution.secChUa, along with the successful proxy, when submitting the token. With the single-proxy example above, use the same SOLVETHREE_PROXY. Don't mix in an unrelated browser identity or target URL.

ready means solvethree generated a solution. Check the target application's response separately to determine whether it accepted your request.