# Compatible format API

> The createTask format other providers use, so existing clients work unchanged. Its errors come in its errorId shape, with HTTP 200; only a failure outside the endpoint, such as a body over the size limit, is a problem document.

Source: https://zerocaptcha.io/docs/reference/api/compatible

## Create a task (compatible)

`POST /createTask` (`compatCreateTask`)

The createTask call other providers use. The body is
`{"clientKey": "…", "task": {"type": "TurnstileTaskProxyless", "websiteURL": "…", "websiteKey": "…"}}`;
the reply is `{"errorId": 0, "taskId": "…"}`. An `Idempotency-Key` header
works as it does on REST. Creations share the key's and the account's
budgets, if the service sets any, with `POST /v1/tasks`. Over one, the
reply is `ERROR_RATE_LIMIT` with `Retry-After`, and nothing is created or
charged.

| Parameter | In | Required | What it is |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | no | Your ID for this task, 1 to 255 visible ASCII characters, as on `POST /v1/tasks`. |

Body fields:

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `clientKey` | string | yes | Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`. |
| `task` | CompatAnyTask | yes | A Turnstile task, or a Cloudflare challenge page's, told apart by `type`. A missing task or `type` is `ERROR_TASK_ABSENT`, another type, a proxyless challenge among them, `ERROR_TASK_NOT_SUPPORTED`, and any other invalid field `ERROR_INVALID_TASK_DATA`. |
| `callbackUrl` | string (uri) or null | no | Where to POST the result once the task ends, signed with your callback secret (`ZeroCaptcha-Signature`): an http or https URL of at most 2048 characters, without credentials, naming a public domain or a public IP address on a port no other protocol reserves. A call that is not answered 2xx is retried with backoff, eight attempts in all over roughly 65 to 95 minutes; one to a name that resolves to a private address is not made. `callbackUrl` in this dialect. |

Responses:

- 200 OK: `errorId` 0 with `taskId`, or 1 with `errorCode` and `errorDescription`.
- Any other status: Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.

```bash
curl -X POST https://api.zerocaptcha.io/createTask \
  -H "Idempotency-Key: order-4521-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "TurnstileTaskProxyless",
    "websiteKey": "0x4AAAAAAAB1cD2eF3gH4iJ5",
    "websiteURL": "https://example.com/login"
  }
}'
```

```js
const response = await fetch("https://api.zerocaptcha.io/createTask", {
  method: "POST",
  headers: {
    "Idempotency-Key": "order-4521-attempt-1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "TurnstileTaskProxyless",
      "websiteKey": "0x4AAAAAAAB1cD2eF3gH4iJ5",
      "websiteURL": "https://example.com/login"
    }
  }),
});
console.log(response.status, await response.text());
```

```python
import requests

response = requests.post(
    "https://api.zerocaptcha.io/createTask",
    headers={"Idempotency-Key": "order-4521-attempt-1"},
    json={
        "clientKey": "YOUR_API_KEY",
        "task": {
            "type": "TurnstileTaskProxyless",
            "websiteKey": "0x4AAAAAAAB1cD2eF3gH4iJ5",
            "websiteURL": "https://example.com/login",
        },
    },
    timeout=30,
)
print(response.status_code, response.text)
```

## Report how a token did (CapSolver)

`POST /feedbackTask` (`compatFeedbackTask`)

CapSolver's `feedbackTask`: `{"clientKey": "…", "taskId": "…", "result":
{"invalid": true}}` says the site refused the token, `false` that it took
it; `invalid` may also come beside `result`. Recorded for our staff, never
refunded. Without `invalid`, `ERROR_INVALID_REQUEST`.

Body fields:

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `clientKey` | string | yes | Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`. |
| `result` | CompatFeedbackResult | yes | What the site made of the token. |
| `taskId` | string (uuid) | yes | The task's ID, as createTask gave it. |

Responses:

- 200 OK: `errorId` 0 with `status: "success"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.
- Any other status: Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.

```bash
curl -X POST https://api.zerocaptcha.io/feedbackTask \
  -H "Content-Type: application/json" \
  -d '{
  "clientKey": "YOUR_API_KEY",
  "result": {
    "invalid": true
  },
  "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
}'
```

```js
const response = await fetch("https://api.zerocaptcha.io/feedbackTask", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientKey": "YOUR_API_KEY",
    "result": {
      "invalid": true
    },
    "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
  }),
});
console.log(response.status, await response.text());
```

```python
import requests

response = requests.post(
    "https://api.zerocaptcha.io/feedbackTask",
    json={
        "clientKey": "YOUR_API_KEY",
        "result": {
            "invalid": True,
        },
        "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

## Get the balance (compatible)

`POST /getBalance` (`compatGetBalance`)

`{"clientKey": "…"}`; the reply is `{"errorId": 0, "balance": 12.3456}`,
the available balance in US dollars, printed exactly. Reads share their budgets with REST; over one, the reply is
`ERROR_RATE_LIMIT` with `Retry-After`.

Body fields:

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `clientKey` | string | yes | Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`. |

Responses:

- 200 OK: The balance, or an error in the dialect's shape.
- Any other status: Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.

```bash
curl -X POST https://api.zerocaptcha.io/getBalance \
  -H "Content-Type: application/json" \
  -d '{
  "clientKey": "YOUR_API_KEY"
}'
```

```js
const response = await fetch("https://api.zerocaptcha.io/getBalance", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientKey": "YOUR_API_KEY"
  }),
});
console.log(response.status, await response.text());
```

```python
import requests

response = requests.post(
    "https://api.zerocaptcha.io/getBalance",
    json={
        "clientKey": "YOUR_API_KEY",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

## Get a task's result (compatible)

`POST /getTaskResult` (`compatGetTaskResult`)

`{"clientKey": "…", "taskId": "…"}`. While the task runs the reply is
`{"errorId": 0, "status": "processing"}`; once solved it is
`status: "ready"` with `solution.token` and `cost`, and for a challenge
page `solution.userAgent` and `solution.cookies` too. A failed task, or one
whose token expired, replies with `errorId: 1` and its `errorCode`. Polls
share the budgets for reads with REST; over one, the reply is
`ERROR_RATE_LIMIT` with `Retry-After`.

Body fields:

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `clientKey` | string | yes | Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`. |
| `taskId` | string (uuid) | yes | The task's ID, as createTask gave it. One that names no task of this key's account is `ERROR_NO_SUCH_CAPCHA_ID`. |

Responses:

- 200 OK: The task's state, or an error in the dialect's shape.
- Any other status: Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.

```bash
curl -X POST https://api.zerocaptcha.io/getTaskResult \
  -H "Content-Type: application/json" \
  -d '{
  "clientKey": "YOUR_API_KEY",
  "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
}'
```

```js
const response = await fetch("https://api.zerocaptcha.io/getTaskResult", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientKey": "YOUR_API_KEY",
    "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
  }),
});
console.log(response.status, await response.text());
```

```python
import requests

response = requests.post(
    "https://api.zerocaptcha.io/getTaskResult",
    json={
        "clientKey": "YOUR_API_KEY",
        "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

## Report a token that worked (2Captcha)

`POST /reportCorrect` (`compatReportCorrect`)

2Captcha's `reportCorrect`: `{"clientKey": "…", "taskId": "…"}` says the
site took the solved task's token. Recorded for our staff; one report per
task, on a task that succeeded.

Body fields:

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `clientKey` | string | yes | Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`. |
| `taskId` | string (uuid) | yes | The task's ID, as createTask gave it. One that names no task of this key's account is `ERROR_NO_SUCH_CAPCHA_ID`. |

Responses:

- 200 OK: `errorId` 0 with `status: "success"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.
- Any other status: Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.

```bash
curl -X POST https://api.zerocaptcha.io/reportCorrect \
  -H "Content-Type: application/json" \
  -d '{
  "clientKey": "YOUR_API_KEY",
  "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
}'
```

```js
const response = await fetch("https://api.zerocaptcha.io/reportCorrect", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientKey": "YOUR_API_KEY",
    "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
  }),
});
console.log(response.status, await response.text());
```

```python
import requests

response = requests.post(
    "https://api.zerocaptcha.io/reportCorrect",
    json={
        "clientKey": "YOUR_API_KEY",
        "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

## Report a token that worked (Anti-Captcha)

`POST /reportCorrectRecaptcha` (`compatReportCorrectRecaptcha`)

Anti-Captcha's `reportCorrectRecaptcha`: the same as `/reportCorrect`.

Body fields:

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `clientKey` | string | yes | Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`. |
| `taskId` | string (uuid) | yes | The task's ID, as createTask gave it. One that names no task of this key's account is `ERROR_NO_SUCH_CAPCHA_ID`. |

Responses:

- 200 OK: `errorId` 0 with `status: "success"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.
- Any other status: Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.

```bash
curl -X POST https://api.zerocaptcha.io/reportCorrectRecaptcha \
  -H "Content-Type: application/json" \
  -d '{
  "clientKey": "YOUR_API_KEY",
  "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
}'
```

```js
const response = await fetch("https://api.zerocaptcha.io/reportCorrectRecaptcha", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientKey": "YOUR_API_KEY",
    "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
  }),
});
console.log(response.status, await response.text());
```

```python
import requests

response = requests.post(
    "https://api.zerocaptcha.io/reportCorrectRecaptcha",
    json={
        "clientKey": "YOUR_API_KEY",
        "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

## Report a refused token (2Captcha)

`POST /reportIncorrect` (`compatReportIncorrect`)

2Captcha's `reportIncorrect`: `{"clientKey": "…", "taskId": "…"}` says the
site refused the solved task's token. It is recorded for our staff, who
watch the solvers' quality with it; tasks are final, so it refunds
nothing. One report per task, on a task that succeeded.

Body fields:

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `clientKey` | string | yes | Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`. |
| `taskId` | string (uuid) | yes | The task's ID, as createTask gave it. One that names no task of this key's account is `ERROR_NO_SUCH_CAPCHA_ID`. |

Responses:

- 200 OK: `errorId` 0 with `status: "success"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.
- Any other status: Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.

```bash
curl -X POST https://api.zerocaptcha.io/reportIncorrect \
  -H "Content-Type: application/json" \
  -d '{
  "clientKey": "YOUR_API_KEY",
  "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
}'
```

```js
const response = await fetch("https://api.zerocaptcha.io/reportIncorrect", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientKey": "YOUR_API_KEY",
    "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
  }),
});
console.log(response.status, await response.text());
```

```python
import requests

response = requests.post(
    "https://api.zerocaptcha.io/reportIncorrect",
    json={
        "clientKey": "YOUR_API_KEY",
        "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b",
    },
    timeout=30,
)
print(response.status_code, response.text)
```

## Report a refused token (Anti-Captcha)

`POST /reportIncorrectRecaptcha` (`compatReportIncorrectRecaptcha`)

Anti-Captcha's `reportIncorrectRecaptcha`, which its clients send for a
token task: the same as `/reportIncorrect`. Recorded, never refunded.

Body fields:

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `clientKey` | string | yes | Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`. |
| `taskId` | string (uuid) | yes | The task's ID, as createTask gave it. One that names no task of this key's account is `ERROR_NO_SUCH_CAPCHA_ID`. |

Responses:

- 200 OK: `errorId` 0 with `status: "success"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.
- Any other status: Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.

```bash
curl -X POST https://api.zerocaptcha.io/reportIncorrectRecaptcha \
  -H "Content-Type: application/json" \
  -d '{
  "clientKey": "YOUR_API_KEY",
  "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
}'
```

```js
const response = await fetch("https://api.zerocaptcha.io/reportIncorrectRecaptcha", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientKey": "YOUR_API_KEY",
    "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b"
  }),
});
console.log(response.status, await response.text());
```

```python
import requests

response = requests.post(
    "https://api.zerocaptcha.io/reportIncorrectRecaptcha",
    json={
        "clientKey": "YOUR_API_KEY",
        "taskId": "0192f3a4-7b1c-7d2e-9f10-3c4d5e6f7a8b",
    },
    timeout=30,
)
print(response.status_code, response.text)
```