# Create a task

> POST /createTask: Create a task. Noptcha API reference.

Source: https://noptcha.com/docs/api-reference/compat-create-task/

POST https://api.noptcha.com/createTask

Compatibility API (anti-captcha compatible). [Guide](https://noptcha.com/docs/compatibility-api.md). Operation ID `compatCreateTask`.

Creates a task and returns its integer `taskId`; poll it with `/getTaskResult`.

When the solver answers synchronously (image types on our own models), the response already has `status: "ready"`, `solution` and `cost`; polling it afterwards returns the same result. When such a synchronous attempt fails, the response is the task's error (for example `ERROR_CAPTCHA_UNSOLVABLE`) and no task ID is returned; nothing is charged.

`softId` / `appId` (digits) are recorded with the task for the developer programme.

## Request

Authentication: the key in the `clientKey` body field ([Keys](https://noptcha.com/docs/authentication.md)).

Body (`application/json`, required):

| Field | Type | Description |
| --- | --- | --- |
| `clientKey`  required  | `string` |  Your key (`nop_live_…` or `nop_test_…`).  |
| `appId`  optional  | `integer | string` |  Same as `softId`.  |
| `callbackUrl`  optional  | `string` |  Where to POST the final result (the `getTaskResult` response plus `taskId`, see the `compatCallback` webhook). Same rules as v1 `callback_url`; an invalid URL is `ERROR_INCORRECT_SESSION_DATA`. Empty: no callback.  max length 2,048  |
| `softId`  optional  | `integer | string` |  Developer programme ID (digits); recorded with the task.  |
| `task`  required  | `object` |  The task in anti-captcha's format: `type` (see `CompatTaskType`) plus that type's fields (`websiteURL`, `websiteKey`, `body`, …; the field map per name is in `CompatTaskType`). Unknown fields are ignored. Parameters are validated against the canonical type's schema (see `CreateTaskRequest`).  Proxy names (`…Task`, without `Proxyless`) need a proxy: `proxyType` (`http`, `https`, `socks4`, `socks5`), `proxyAddress`, `proxyPort`, optional `proxyLogin` and `proxyPassword`; or `proxy` as a URL string `http://user:pass@host:port`. Proxyless names ignore proxy fields.  |
| `task.proxyAddress`  optional  | `string` |  |
| `task.proxyLogin`  optional  | `string` |  |
| `task.proxyPassword`  optional  | `string` |  |
| `task.proxyPort`  optional  | `integer | string` |  |
| `task.proxyType`  optional  | `enum` |  one of "http", "https", "socks4", "socks5"  |
| `task.type`  required  | `string` |  Task type name in the compatibility API (case-insensitive). Each name maps to a canonical type and variant (see `CreateTaskRequest` for the parameters). Names ending in `Proxyless` ignore proxy fields; the others require a proxy. Unknown names: `ERROR_TASK_NOT_SUPPORTED`.  `x-noptcha-aliases` lists, per name, `fields` (compatibility field → canonical parameter; `null`: accepted but not passed on; `to_array`: a single value is wrapped in an array) and `solution` (canonical solution field → compatibility field; `index_bools`: selected indexes become one boolean per image or tile). 
| Name | Canonical type | Variant | Notes |
| --- | --- | --- | --- |
| `FunCaptchaClassification` | `image.funcaptcha` | proxyless |  |
| `FunCaptchaTask` | `funcaptcha` | proxy |  |
| `FunCaptchaTaskProxyless` | `funcaptcha` | proxyless |  |
| `HCaptchaClassification` | `image.grid.hcaptcha` | proxyless |  |
| `HCaptchaTask` | `hcaptcha` | proxy |  |
| `HCaptchaTaskProxyless` | `hcaptcha` | proxyless |  |
| `ImageToTextTask` | `image.text` | proxyless |  |
| `NoCaptchaTask` | `recaptcha.v2` | proxy |  |
| `NoCaptchaTaskProxyless` | `recaptcha.v2` | proxyless |  |
| `ReCaptchaV2Classification` | `image.grid.recaptcha` | proxyless |  |
| `RecaptchaV2EnterpriseTask` | `recaptcha.v2.enterprise` | proxy |  |
| `RecaptchaV2EnterpriseTaskProxyless` | `recaptcha.v2.enterprise` | proxyless |  |
| `RecaptchaV2Task` | `recaptcha.v2` | proxy |  |
| `RecaptchaV2TaskProxyless` | `recaptcha.v2` | proxyless |  |
| `RecaptchaV3EnterpriseTask` | `recaptcha.v3.enterprise` | proxyless |  |
| `RecaptchaV3TaskProxyless` | `recaptcha.v3` | proxyless | `isEnterprise: true` → `recaptcha.v3.enterprise` |
| `TurnstileTask` | `turnstile` | proxy |  |
| `TurnstileTaskProxyless` | `turnstile` | proxyless |  |

 |

Example

```json
{
  "clientKey": "nop_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "task": {
    "type": "RecaptchaV2TaskProxyless",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    "websiteURL": "https://example.com/login"
  }
}
```

## Responses

### 200

Created (`errorId` 0) or rejected (`errorId` 1).

Headers: `Noptcha-Request-Id`.

Content: `application/json`

One of:

-   `CompatCreateTaskResult`
-   `CompatError` — A request or task error. `errorCode` values (anti-captcha's codes; new ones may be added):

### 403

`forbidden` (problem details): the request reached the API without passing through our edge network. Infrastructure, not part of the compatibility protocol.

Headers: `Noptcha-Request-Id`.

Content: `application/problem+json`

| Field | Type | Description |
| --- | --- | --- |
| `code`  required  | `string` |  Machine-readable error code (see the table).  |
| `detail`  optional  | `string` |  Human-readable explanation of this occurrence.  |
| `request_id`  required  | `string` |  Same as the `Noptcha-Request-Id` header.  |
| `status`  required  | `integer` |  The HTTP status code.  |
| `title`  required  | `string` |  |
| `type`  required  | `string` |  format: uri  |

### 500

`internal`: an error on our side.

Headers: `Noptcha-Request-Id`, `RateLimit` (optional), `RateLimit-Policy` (optional).

Content: `application/problem+json`

| Field | Type | Description |
| --- | --- | --- |
| `code`  required  | `string` |  Machine-readable error code (see the table).  |
| `detail`  optional  | `string` |  Human-readable explanation of this occurrence.  |
| `request_id`  required  | `string` |  Same as the `Noptcha-Request-Id` header.  |
| `status`  required  | `integer` |  The HTTP status code.  |
| `title`  required  | `string` |  |
| `type`  required  | `string` |  format: uri  |

**About the compatibility API:**

The anti-captcha compatible JSON protocol.

-   Requests are `POST` with a JSON body. `Content-Type` is not required; the body is always parsed as JSON.
-   The key goes in `clientKey`. The key is checked before anything else, so an invalid key is reported even when other fields are wrong.
-   Responses are always HTTP 200. `errorId` is 0 on success and 1 on error; then `errorCode` and `errorDescription` say what went wrong (see `CompatError` for every code).
-   Two responses come from the infrastructure, not from the protocol: `403` (problem details, code `forbidden`) when a request reaches the API without passing through our edge network, and `500` (code `internal`) on an unexpected server error. Treat both as transient errors.
-   An unknown path, or a known path with another method (for example `GET /createTask`), is `404` (problem details, code `not_found`).
-   Task type names are the common anti-captcha compatible names (case-insensitive); each maps to a canonical type and variant, see `CompatTaskType`.
-   `callbackUrl` (optional) receives the final result as a POST (see Webhooks and the `compatCallback` webhook). An invalid URL is `ERROR_INCORRECT_SESSION_DATA` and no task is created.

Header descriptions and every schema: [Schemas](https://noptcha.com/docs/api-reference/schemas.md). Machine-readable: [openapi.json](https://noptcha.com/openapi.json), [openapi.yaml](https://noptcha.com/openapi.yaml).