AWS WAF CAPTCHA Solver API: aws-waf-token via REST

Solve AWS WAF challenge and CAPTCHA with the SolveHub API: challenge script URL, optional captcha script and proxy, returning an aws-waf-token. Request fields, cURL example and errors.

For authorized QA automation and browser integration. Use only on websites and workflows you have permission to test.

Requires the protected page websiteURL and the full challenge script URL WafScriptUrl (note the casing). An HTTP proxy is optional; this type does not accept a custom useragent field. The script URL should be taken from the actual AWS WAF challenge page.

Request fields

The top-level type and task are required; all task.* paths below are inside the task object. Field names are case-sensitive. Length limits are measured in UTF-8 bytes.

Field	Type	Required	Limits	Description
`type`	String	Yes	Always `awswaf`	Platform task type.
`task`	JSON object	Yes	≤ 7 MiB	Task parameters for this type.
`task.type`	String	No	Must be `awswaf` if provided	Kept for compatibility with the legacy request format; can be omitted in new integrations.
`task.websiteURL`	HTTP(S) URL	Yes	≤ 2048 bytes	Full URL of the target page to solve, without credentials.
`task.WafScriptUrl`	HTTP(S) URL	Yes	≤ 4096 bytes	Full URL of the AWS WAF challenge script injected into the target page; the field name is case-sensitive.
`task.proxyType`	String	No	`http` only	Proxy protocol; must be `http` when provided.
`task.proxyAddress`	String	No	≤ 256 bytes	Proxy IP or hostname; must be provided together with `proxyPort`.
`task.proxyPort`	String	No	1–5 bytes, value 1–65535	Proxy port; must be a quoted numeric string.
`task.proxyLogin`	String	No	≤ 256 bytes	Username, if the proxy requires authentication; must not be provided without the address and port.
`task.proxyPassword`	String	No	≤ 256 bytes	Password, if the proxy requires authentication; must not be provided without the address and port.

Create request example

{
  "type": "awswaf",
  "task": {
    "websiteURL": "https://example.com/protected",
    "WafScriptUrl": "https://example.com/challenge.js"
  }
}

cURL call

Replace the key, site details, and proxy in the example with your actual values; keep the Idempotency-Key unchanged for the same business request.

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-awswaf-0001' \
  --data-binary @- <<'JSON'
{
  "type": "awswaf",
  "task": {
    "websiteURL": "https://example.com/protected",
    "WafScriptUrl": "https://example.com/challenge.js"
  }
}
JSON

Create response and polling

A successful create returns HTTP 202, and status is usually queued initially. Save the taskId and call GET /v1/tasks/{taskId} about every 2–3 seconds. The soft processing time limit for this type is 180 seconds; after the soft limit the task may enter uncertain, and the results of accepted tasks can still be verified. Clients should not blindly recreate the task with a new Idempotency-Key.

Result fields

Read solution only when status=completed; the table below lists common fields, and the actual fields are determined by the task response.

Field	Type	How to read
`solution.value`	String, optional	May directly contain the verification token.
`solution.cookies`	Object, optional	May contain the `aws-waf-token` cookie; the actual response is authoritative.
`solution.useragent`	String, optional	When a custom proxy is used, reuse it together with the same egress.

After completion, obtain the token from solution.value or solution.cookies["aws-waf-token"], and send it as the aws-waf-token cookie as required by the target service. Example result: {"value":"EXAMPLE_TOKEN","cookies":{"aws-waf-token":"EXAMPLE_TOKEN"},"useragent":"Mozilla/5.0 ..."}. If a proxy was provided, subsequent requests should use the same egress and solution.useragent.

Failures and troubleshooting

You must provide the actual challenge script URL, and the field name must be exactly WafScriptUrl; a custom useragent request field is not supported.

Common errors for create requests are 400 INVALID_TASK, 402 INSUFFICIENT_BALANCE, 429 TASK_LIMIT_EXCEEDED, and 503 TYPE_UNAVAILABLE. When a created task fails, the public error code is TASK_FAILED or TASK_TIMEOUT; uncertain corresponds to TASK_UNCERTAIN. See the Platform API reference for details.

The processing window starts after task creation is confirmed; queue waiting does not consume it. The current node timeout is approximately 100 seconds; the platform allows a 180-second soft window for transport and result polling.