> For the complete documentation index, see [llms.txt](https://dinproxy.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dinproxy.gitbook.io/docs/guides/web-unlocker/api-reference.md).

# API reference

Endpoint, parameters, responses and errors of the Web Unlocker.

## Endpoint

```http
POST https://app.dinproxy.com/api/unblocker/request
Content-Type: application/json
Authorization: Basic BASE64(username:password)
```

Sign in with HTTP Basic authentication using a [proxy user](https://dinproxy.gitbook.io/docs/getting-started/proxy-users.md): its connection username (e.g. `1024~myuser`) and password. Most clients do this for you, e.g. `curl --user '1024~myuser:YOUR_PASSWORD'`.

## Parameters

Send the parameters as a JSON object. Only `target_url` is required.

| Parameter          | Type    | Default | Description                                                                                                                                        |
| ------------------ | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target_url`       | string  | —       | The page to fetch. A public `http` or `https` URL on port 80 or 443, without a `#fragment` or `user:password@`.                                    |
| `response_format`  | string  | `html`  | `html`, `png` (screenshot) or `html,png` (both).                                                                                                   |
| `js_render`        | boolean | `true`  | Run the page's JavaScript before returning it.                                                                                                     |
| `country`          | string  | any     | Two-letter country code to fetch from, e.g. `us`.                                                                                                  |
| `wait_ms`          | integer | —       | Extra time to wait after loading, in milliseconds (0 to 100000).                                                                                   |
| `wait_selector`    | string  | —       | Wait until an element matching this CSS selector appears (up to 512 characters).                                                                   |
| `auto_runs`        | integer | `2`     | How many times to retry a failed attempt (0 to 10).                                                                                                |
| `follow_redirects` | boolean | —       | Whether to follow redirects.                                                                                                                       |
| `block_resources`  | string  | —       | Skip loading resources: any of `image`, `javascript`, `video`, comma-separated.                                                                    |
| `clear`            | string  | —       | Remove `js` and/or `css` from the returned HTML, comma-separated.                                                                                  |
| `headers`          | object  | —       | Extra request headers, as `{"Name": "value"}`. `Host`, `Proxy-Authorization`, `Connection`, `Content-Length` and `Transfer-Encoding` can't be set. |
| `cookies`          | object  | —       | Cookies to send, as `{"name": "value"}`.                                                                                                           |

`wait_ms × (auto_runs + 1)` may not exceed 100000, so a request always fits in its 2-minute window. Unknown parameters are refused.

## Response

A successful request returns HTTP 200:

```json
{
  "success": true,
  "data": {
    "html": "<!doctype html>…",
    "png": "iVBORw0KGgo…",
    "final_url": "https://example.com/",
    "status_code": 200
  }
}
```

`html` is present when you asked for HTML, `png` (a base64-encoded image) when you asked for a screenshot. When known, `final_url` is where the page ended up after redirects and `status_code` is the status the site answered with.

## Billing

* Each successful result uses **1 result** from your balance, whatever the response format.
* Failed requests use nothing.
* A request may take up to **2 minutes**; set your client timeout above that (e.g. 130 s). A result that succeeds after your client gave up is still charged, so use an `Idempotency-Key` to collect it.

## Retrying safely

Add an `Idempotency-Key` header with a unique value of your choice (up to 128 letters, digits or `. _ : -`):

```bash
curl --request POST 'https://app.dinproxy.com/api/unblocker/request' \
  --user '1024~myuser:YOUR_PASSWORD' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1234-page-1' \
  --data '{"target_url": "https://example.com"}' \
  --max-time 130
```

* Repeating the **same request with the same key within 24 hours** returns the stored result without another charge. The answer carries `Idempotency-Replayed: true`.
* Use each key for one request only. The same key with **different parameters**, or from another proxy user of your account, is refused with `409 IDEMPOTENCY_CONFLICT`.
* While the first request is still running, a repeat gets `409 REQUEST_IN_PROGRESS`; wait and try again.
* After a `502` or `504` the request failed and was not charged. To try again, use a **new key**: the same key keeps returning that error.
* After 24 hours the stored result is gone: `410 RESULT_EXPIRED`.

## Errors

Errors return `{"success": false, "code": "…"}` with these HTTP statuses. A body that is not valid JSON gets `400` and a body larger than 64 KB gets `413`, both with `{"success": false, "message": "Bad request"}`.

If you get `524` or no answer at all, repeat the request with the same `Idempotency-Key` to collect the result without paying twice.

| Status     | Code                                                                                                           | Meaning                                                                                                                              |
| ---------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 400        | `INVALID_REQUEST`, `UNSUPPORTED_PARAMETER`, `INVALID_PARAMETER`                                                | The body is not a JSON object, or a parameter is unknown or has a wrong value                                                        |
| 400        | `INVALID_TARGET`                                                                                               | `target_url` is missing or is not a public `http`/`https` URL on port 80 or 443 (no `#fragment`, no `user:password@`)                |
| 400        | `INVALID_FORMAT`, `INVALID_COUNTRY`, `INVALID_WAIT`, `INVALID_AUTO_RUNS`, `INVALID_SELECTOR`, `INVALID_HEADER` | The named parameter is invalid                                                                                                       |
| 400        | `INVALID_IDEMPOTENCY_KEY`                                                                                      | The key is too long or has other characters                                                                                          |
| 401        | `AUTHENTICATION_FAILED`                                                                                        | Wrong or missing username or password                                                                                                |
| 402        | `RESULT_BALANCE_EXHAUSTED`                                                                                     | No results left: buy more on the Web Unlocker page                                                                                   |
| 403        | `ADDRESS_BLOCKED`                                                                                              | Your IP tried 20 different wrong passwords within a day and is blocked for 24 hours. Contact support to lift it sooner               |
| 409        | `IDEMPOTENCY_CONFLICT`, `REQUEST_IN_PROGRESS`                                                                  | See [Retrying safely](#retrying-safely)                                                                                              |
| 410        | `RESULT_EXPIRED`                                                                                               | The stored result for this key is older than 24 hours                                                                                |
| 429        | `TOO_MANY_REQUESTS`                                                                                            | More than 100 requests at once for your account (API, proxy mode, MCP and CLI together), or too many per minute: slow down and retry |
| 429        | `TOO_MANY_FAILED_LOGINS`                                                                                       | Too many wrong passwords: wait (see `Retry-After`)                                                                                   |
| 502        | `UNBLOCKER_UPSTREAM_FAILED`                                                                                    | The page could not be fetched this time. Not charged; retry with a new `Idempotency-Key`                                             |
| 502        | `ACCOUNT_CHANGED`                                                                                              | The proxy user was paused or its password changed during the request. Not charged                                                    |
| 502 or 504 | `REQUEST_EXPIRED`                                                                                              | The request took too long and was abandoned. Not charged; retry with a new `Idempotency-Key`                                         |
| 503        | `UNBLOCKER_UNAVAILABLE`, `SERVICE_UNAVAILABLE`                                                                 | Temporarily unavailable; try again shortly                                                                                           |
