# 🔌 OpenAPI

EProxies exposes 5 HTTP endpoints (whitelist-mode proxy extraction and whitelist management). This page is a quick reference; for detailed usage see [API Extraction (Whitelist Mode)](https://www.eproxies.io/docs/usage/api-extraction).

> Machine-readable definition: [openapi.json](https://www.eproxies.io/docs/openapi.json) — an OpenAPI 3.0 spec you can import straight into Postman / Swagger UI / Insomnia, or hand to an AI agent to call automatically.

## Basics

| Item | Value |
| --- | --- |
| Base URL | `https://api.eproxies.net` |
| Auth (extraction) | Request must originate from a **whitelisted IP**; no credentials needed |
| Auth (management) | Query params `userName` + `userKeyValue` (user key, from the dashboard) |
| Proxy gateway | `proxy.eproxies.net:23333` (HTTP/HTTPS/SOCKS5 — not part of this HTTP API) |

## Endpoints

### `GET /gateway_api/extract_ip`

Extract proxies — Extract a batch of proxy endpoints. The request must originate from a whitelisted IP; the returned proxies are used directly, without credentials.

**Request parameters**

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `count` | integer | Yes | `1` ~ N | Number of proxies to extract |
| `country` | string | No | `US` `GB` `JP` … / `Global` | ISO 3166-1 alpha-2 country code; `Global` means any country |
| `protocol` | string | No | `http` / `socks5` | Proxy protocol |
| `format` | string | No | `txt` / `json` | Response format; `json` returns an object array, `txt` returns plain-text lines |
| `separator` | string | No | `crlf` `br` `cr` `lf` `tab` | Separator for `txt` format: `\r\n`, `</br>`, `\r`, `\n`, `\t` respectively |
| `st` | string | No | — | Custom separator; overrides `separator` when set |
| `session` | string | No | `sticky` / `random` | IP type: `sticky` reuses the same batch of IPs, `random` returns random ones |

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `ipAddress` | string | Proxy IP address |
| `portValue` | integer | Proxy port |

With `format=json` the response is an array of the objects above; with `format=txt` it is `IP:port` text lines joined by `separator`.

**Example**

```bash
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"
```

```json
[
  { "ipAddress": "203.0.113.10", "portValue": 23333 },
  { "ipAddress": "203.0.113.11", "portValue": 23333 }
]
```

### `GET /gateway_api/country-list`

Supported countries — List every country available for whitelist-mode extraction.

**Request parameters**

No request parameters.

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `country` | string | ISO 3166-1 alpha-2 code — use it as the `country` parameter of `extract_ip` |
| `name` | string | Country name |
| `flag_url` | string | Flag icon URL |

**Example**

```bash
curl "https://api.eproxies.net/gateway_api/country-list"
```

```json
[
  { "country": "US", "name": "United States", "flag_url": "https://file.eproxies.net/flags/us.png" }
]
```

### `GET /gateway_api/add-ip`

Add a whitelist IP — Add an exit IP to the whitelist; that IP can then extract proxies without credentials.

**Request parameters**

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `userName` | string | Yes | — | Account username |
| `userKeyValue` | string | Yes | — | User key, from the dashboard |
| `ipAddress` | string | Yes | — | IP address to whitelist |

**Response fields**

Returns an operation-result object; refer to the actual response.

**Example**

```bash
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

### `GET /gateway_api/del-ip`

Delete a whitelist IP — Remove an IP from the whitelist; it can no longer extract without credentials.

**Request parameters**

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `userName` | string | Yes | — | Account username |
| `userKeyValue` | string | Yes | — | User key, from the dashboard |
| `ipAddress` | string | Yes | — | Whitelist IP to remove |

**Response fields**

Returns an operation-result object; refer to the actual response.

**Example**

```bash
curl "https://api.eproxies.net/gateway_api/del-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

### `GET /gateway_api/lists-ip`

List whitelist entries — List all whitelist entries under the current account.

**Request parameters**

| Field | Type | Required | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `userName` | string | Yes | — | Account username |
| `userKeyValue` | string | Yes | — | User key, from the dashboard |

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `ipAddress` | string | Whitelisted IP |
| `remarkText` | string | Remark |

**Example**

```bash
curl "https://api.eproxies.net/gateway_api/lists-ip?userName=USERNAME&userKeyValue=USER_KEY"
```

## Quick call

```bash
# Extract 10 US HTTP proxies (JSON, sticky IPs)
curl "https://api.eproxies.net/gateway_api/extract_ip?count=10&country=US&protocol=http&format=json&session=sticky"

# Whitelist the current server IP
curl "https://api.eproxies.net/gateway_api/add-ip?userName=USERNAME&userKeyValue=USER_KEY&ipAddress=203.0.113.10"
```

## Using it from an AI agent

Point your agent at the spec URL and it can work out every parameter and response shape on its own:

```
https://www.eproxies.io/docs/openapi.json
```

Together with the [Agent Cheat Sheet](https://www.eproxies.io/docs/agent-reference) (username parameter syntax for the proxy gateway) this covers the full integration surface.