Proxy587 API

The Proxy587 API allows you to programmatically manage your proxies, create orders, extend subscriptions, and automate your proxy infrastructure. This documentation covers all available endpoints.

Base URL

https://proxy587.com/api/v1
Secure

API key + IP whitelist authentication

Fast

Instant order processing and proxy assignment

RESTful

Standard JSON request/response format

Authentication

All API requests require authentication using an API key. Generate your API key in the Telegram Bot settings.

Security Requirements

  1. 1
    API Key

    Include your 64-character API key in the Authorization header using Bearer token format.

  2. 2
    IP Whitelist

    Requests are only accepted from whitelisted IP addresses (max 3 IPs). Configure in the bot settings.

Example Request

curl -X GET "https://proxy587.com/api/v1/balance" \
  -H "Authorization: Bearer your-64-character-api-key-here"

Rate Limits

API requests are rate limited to ensure fair usage and system stability:

Endpoint Type Rate Limit Description
GET endpoints 100 req/min Balance, formats, countries, proxies list
POST orders 10 req/min Order creation
POST replacement 5 req/min Replacement requests
POST proxies/parent/rotate 10 req/min Parent rotation (intended for non-working originals)

Errors

The API uses standard HTTP status codes and returns JSON error responses. All responses include a status field.

Code Status Description
200 OK Request successful
400 Bad Request Invalid parameters or malformed request
401 Unauthorized Invalid or missing API key
402 Payment Required Insufficient balance
403 Forbidden IP not in whitelist or feature not enabled
404 Not Found Resource doesn't exist
429 Rate Limit Too many requests, slow down

Error Response Format

{
  "status": "error",
  "data": {},
  "errors": ["Invalid API key"]
}
GET /balance

Get your current account balance.

Response Fields

FieldTypeDescription
balancestringCurrent balance amount (e.g., "125.50")
currencystringCurrency code (always "USD")

Example Request

curl -X GET "https://proxy587.com/api/v1/balance" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "balance": "125.50",
    "currency": "USD"
  },
  "errors": []
}
GET /formats

Get available proxy formats (IPv4, ISP, IPv6, Mobile).

Response Fields

FieldTypeDescription
formatsarrayList of available proxy formats
formats[].idintegerFormat ID (use in other endpoints)
formats[].namestringHuman-readable format name
formats[].codestringFormat code: ipv4, isp, ipv6, mobile

Example Request

curl -X GET "https://proxy587.com/api/v1/formats" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "formats": [
      {"id": 1, "name": "IPv4", "code": "ipv4"},
      {"id": 2, "name": "ISP", "code": "isp"},
      {"id": 3, "name": "IPv6", "code": "ipv6"},
      {"id": 4, "name": "Mobile", "code": "mobile"}
    ]
  },
  "errors": []
}
GET /countries

Get available countries for proxy orders.

Query Parameters

ParameterTypeRequiredDescription
format_idintegerOptionalFilter by proxy format ID

Response Fields

FieldTypeDescription
countriesarrayList of available countries
countries[].idintegerCountry ID (use in orders)
countries[].namestringCountry name
countries[].codestringISO country code (US, DE, etc.)
countries[].format_idintegerAssociated proxy format ID

Example Request

curl -X GET "https://proxy587.com/api/v1/countries?format_id=1" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "countries": [
      {"id": 1, "name": "United States", "code": "US", "format_id": 1},
      {"id": 2, "name": "Germany", "code": "DE", "format_id": 1},
      {"id": 3, "name": "Netherlands", "code": "NL", "format_id": 1}
    ]
  },
  "errors": []
}
GET /durations

Get available rental durations.

Response Fields

FieldTypeDescription
durationsarrayList of available durations
durations[].daysintegerNumber of days (7, 14, 30, 60, 90)
durations[].labelstringHuman-readable label

Example Request

curl -X GET "https://proxy587.com/api/v1/durations" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "durations": [
      {"days": 7, "label": "7 days"},
      {"days": 14, "label": "14 days"},
      {"days": 30, "label": "30 days"},
      {"days": 60, "label": "60 days"},
      {"days": 90, "label": "90 days"}
    ]
  },
  "errors": []
}
GET /pricing

Calculate order price. Also accepts POST with JSON body.

Query Parameters

ParameterTypeRequiredDescription
format_idintegerRequiredProxy format ID
country_idintegerRequiredCountry ID
durationintegerRequiredDuration in days (7, 14, 30, 60, 90)
quantityintegerRequiredNumber of proxies (1-1000)

Response Fields

FieldTypeDescription
price_per_proxystringPrice per single proxy
total_pricestringFinal total after discounts
original_pricestringPrice before discounts
quantity_discount_percentstringDiscount percentage applied
currencystringCurrency code (USD)

Example Request

curl -X GET "https://proxy587.com/api/v1/pricing?format_id=1&country_id=1&duration=30&quantity=10" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "price_per_proxy": "2.50",
    "total_price": "22.50",
    "original_price": "25.00",
    "quantity_discount_percent": "10",
    "currency": "USD"
  },
  "errors": []
}
GET /subnets

Get available subnets for a country and format. Only available for IPv4 and ISP formats.

Note: Subnet selection must be enabled for your account. Not available for IPv6 and Mobile formats.

Query Parameters

ParameterTypeRequiredDescription
format_idintegerRequiredProxy format ID
country_idintegerRequiredCountry ID

Response Fields

FieldTypeDescription
subnetsarrayList of available subnets
subnets[].subnetstringSubnet prefix (e.g., "192.168.1")

Example Request

curl -X GET "https://proxy587.com/api/v1/subnets?format_id=1&country_id=1" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "subnets": [
      {"subnet": "192.168.1"},
      {"subnet": "10.0.0"},
      {"subnet": "172.16.0"}
    ]
  },
  "errors": []
}
GET /rotation-types

Get available rotation types for mobile proxies in a specific country.

Note: This endpoint is only applicable to countries that support mobile proxy format.

Query Parameters

ParameterTypeRequiredDescription
country_idintegerRequiredCountry ID with mobile proxy support

Response Fields

FieldTypeDescription
rotation_typesarrayList of available rotation types
rotation_types[].valuestringRotation type code (sticky, 5min, 30min)
rotation_types[].labelstringHuman-readable label

Example Request

curl -X GET "https://proxy587.com/api/v1/rotation-types?country_id=5" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "rotation_types": [
      {"value": "sticky", "label": "Sticky (no rotation)"},
      {"value": "5min", "label": "Rotation every 5 minutes"},
      {"value": "30min", "label": "Rotation every 30 minutes"}
    ]
  },
  "errors": []
}
GET /mobile-operators

Get available mobile operators for a specific country and optionally filter by rotation type.

Note: This endpoint is only applicable to countries that support mobile proxy format. Filter by rotation_type to see which operators are available for specific rotation types.

Query Parameters

ParameterTypeRequiredDescription
country_idintegerRequiredCountry ID with mobile proxy support
rotation_typestringOptionalFilter operators by rotation type (sticky, 5min, 30min)

Response Fields

FieldTypeDescription
operatorsarrayList of available mobile operators
operators[].valuestringOperator code (e.g., orange, sfr, vodafone)
operators[].labelstringHuman-readable operator name

Example Request

curl -X GET "https://proxy587.com/api/v1/mobile-operators?country_id=5&rotation_type=sticky" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "operators": [
      {"value": "orange", "label": "Orange"},
      {"value": "sfr", "label": "SFR"},
      {"value": "vodafone", "label": "Vodafone"}
    ]
  },
  "errors": []
}
GET /orders

Get your orders list with filtering options.

Query Parameters

ParameterTypeRequiredDescription
statusstringOptionalFilter: active, expired, all (default: active)

Response Fields

FieldTypeDescription
ordersarrayList of orders
orders[].order_idintegerOrder ID
orders[].formatstringProxy format code
orders[].countrystringCountry code
orders[].quantityintegerNumber of proxies
orders[].duration_daysintegerDuration in days
orders[].created_atstringCreation date (ISO 8601)
orders[].expires_atstringExpiration date (ISO 8601)
orders[].statusstringOrder status: active, expired
totalintegerTotal number of orders

Example Request

curl -X GET "https://proxy587.com/api/v1/orders?status=active" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "orders": [
      {
        "order_id": 12345,
        "format": "ipv4",
        "country": "US",
        "quantity": 10,
        "duration_days": 30,
        "created_at": "2025-11-28T12:00:00Z",
        "expires_at": "2025-12-28T12:00:00Z",
        "status": "active"
      }
    ],
    "total": 1
  },
  "errors": []
}
POST /orders/create

Create a new proxy order. Payment is deducted from your balance.

Request Body

ParameterTypeRequiredDescription
format_idintegerRequiredProxy format ID
country_idintegerRequiredCountry ID
durationintegerRequiredDuration in days (7, 14, 30, 60, 90)
quantityintegerRequiredNumber of proxies (1-1000)
subnetsarrayOptionalPreferred subnet prefixes (IPv4/ISP only)
mobile_rotation_typestringRequired*Rotation type for mobile proxies (sticky, 5min, 30min). *Required for mobile orders only.
mobile_operatorstringRequired*Mobile operator (e.g., orange, sfr, vodafone, or 'any'). *Required for mobile orders only.
allowed_ipstringOptionalIP for IP-based authorization
promo_codestringOptionalPromo code for discount (not available with custom pricing)
universal_loginstringOptionalUniversal login for all proxies (3-32 chars, alphanumeric)
universal_passwordstringOptionalUniversal password for all proxies (6-64 chars)
extra_credentials_countintegerOptionalExtra credential pairs per proxy (0-50)

Response Fields

FieldTypeDescription
order_idstringCreated order ID
total_pricestringAmount charged
payment_statusstringPayment status (paid)
proxies_countintegerNumber of assigned proxies
promo_discount_percentstringPromo discount applied (if any)
quantity_discount_percentstringQuantity discount applied (if any)
extra_credentials_createdintegerNumber of extra credentials created

Example Request

curl -X POST "https://proxy587.com/api/v1/orders/create" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "format_id": 1,
    "country_id": 1,
    "quantity": 10,
    "duration": 30,
    "promo_code": "DISCOUNT10",
    "universal_login": "mylogin",
    "universal_password": "mypassword123",
    "extra_credentials_count": 2
  }'

Example Response 200 OK

{
  "status": "success",
  "data": {
    "order_id": "ORD-20251129-ABCD",
    "total_price": "20.25",
    "payment_status": "paid",
    "proxies_count": 10,
    "promo_discount_percent": "10.00",
    "quantity_discount_percent": "0",
    "extra_credentials_created": 20
  },
  "errors": []
}
GET /orders/{order_id}

Get detailed information about a specific order.

Path Parameters

ParameterTypeRequiredDescription
order_idstringRequiredOrder ID (e.g., ORD-20251129-ABCD)

Response Fields

FieldTypeDescription
order_idstringOrder ID
formatstringProxy format (ipv4, isp, ipv6, mobile)
countrystringCountry code
quantityintegerOrdered quantity
duration_daysintegerDuration in days
pricestringFinal price paid
created_atstringCreation date (ISO 8601)
expires_atstringExpiration date (ISO 8601)
statusstringOrder status: active, expired
payment_statusstringPayment status: paid, unpaid
allowed_ipstring|nullWhitelisted IP for authorization
has_universal_credentialsbooleanWhether universal credentials are set
proxies_countintegerTotal proxies in order
active_proxies_countintegerCurrently active proxies
extra_credentials_countintegerNumber of extra credential pairs

Example Request

curl -X GET "https://proxy587.com/api/v1/orders/ORD-20251129-ABCD" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "order_id": "ORD-20251129-ABCD",
    "format": "ipv4",
    "country": "US",
    "quantity": 10,
    "duration_days": 30,
    "price": "20.25",
    "created_at": "2025-11-29T12:00:00Z",
    "expires_at": "2025-12-29T12:00:00Z",
    "status": "active",
    "payment_status": "paid",
    "allowed_ip": null,
    "has_universal_credentials": true,
    "proxies_count": 10,
    "active_proxies_count": 10,
    "extra_credentials_count": 20
  },
  "errors": []
}
GET /proxies

Get your active proxies with connection details.

Query Parameters

ParameterTypeRequiredDescription
order_idintegerOptionalFilter by order ID
formatstringOptionalFilter: ipv4, isp, ipv6, mobile
countrystringOptionalFilter by country code (US, DE)
protocolstringOptionalhttp or socks5 (default: http)
output_formatstringOptionalCustom format: {ip}:{port}:{login}:{password}

Response Fields

FieldTypeDescription
proxiesarrayList of proxies
proxies[].order_idintegerAssociated order ID
proxies[].ipstringProxy IP (only for IPv4/ISP)
proxies[].hoststringConnection host (IP or domain)
proxies[].port_httpintegerHTTP port
proxies[].port_socks5integerSOCKS5 port
proxies[].loginstringUsername for authentication
proxies[].passwordstringPassword for authentication
proxies[].expires_atstringExpiration date (ISO 8601)
proxies[].countrystringCountry code
proxies[].formatstringFormat code
totalintegerTotal number of proxies

Example Request

curl -X GET "https://proxy587.com/api/v1/proxies?order_id=12345" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "proxies": [
      {
        "order_id": 12345,
        "ip": "185.10.20.30",
        "host": "185.10.20.30",
        "port_http": 8080,
        "port_socks5": 23080,
        "login": "user123",
        "password": "pass456",
        "expires_at": "2025-12-28T12:00:00Z",
        "country": "US",
        "format": "ipv4"
      }
    ],
    "total": 1
  },
  "errors": []
}
POST /proxies/extend

Extend the rental period of existing proxies. Payment deducted from balance.

Request Body

ParameterTypeRequiredDescription
order_idintegerOptional*Extend all proxies in order
proxy_ipsarrayOptional*Extend specific proxies by IP
durationintegerRequiredAdditional days (7, 14, 30, 60, 90)

* Either order_id or proxy_ips is required.

Response Fields

FieldTypeDescription
extended_countintegerNumber of extended proxies
total_pricestringAmount charged
new_expirystringNew expiration date (ISO 8601)

Example Request

curl -X POST "https://proxy587.com/api/v1/proxies/extend" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": 12345,
    "duration": 30
  }'

Example Response 200 OK

{
  "status": "success",
  "data": {
    "extended_count": 10,
    "total_price": "25.00",
    "new_expiry": "2026-01-28T12:00:00Z"
  },
  "errors": []
}
POST /replacement

Submit a replacement request for non-working proxies.

Request Body

ParameterTypeRequiredDescription
proxy_ipsarrayRequiredArray of proxy IPs to replace
reasonstringRequiredReason for replacement
selected_subnetsarrayOptionalPreferred subnets (if enabled)

Response Fields

FieldTypeDescription
request_idintegerReplacement request ID
proxies_countintegerNumber of proxies submitted
statusstringpending or completed

Example Request

curl -X POST "https://proxy587.com/api/v1/replacement" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_ips": ["185.10.20.30", "185.10.20.31"],
    "reason": "Proxies not working for target site"
  }'

Example Response 200 OK

{
  "status": "success",
  "data": {
    "request_id": 789,
    "proxies_count": 2,
    "status": "pending"
  },
  "errors": []
}
POST /proxies/parent/rotate

Rotate the upstream parent of one or more proxies to a random replacement of the same country and format. The original parent is re-tested at +1h, +6h, +12h, +24h, +72h, +168h and automatically restored if it recovers.

Request Body

ParameterTypeRequiredDescription
proxy_ipsarray<string>RequiredOne or more proxy IPs from your account to rotate. proxy_ip (string) is also accepted for a single IP.

Response Fields

FieldTypeDescription
rotatedarrayList of successful rotations. Each entry contains rotation_id, proxy_ip, status, schedule_hours, next_test_at (ISO 8601 UTC).
errorsarrayList of per-IP failures: {"proxy_ip", "error"}. Possible errors: not found or not active, proxy is shared with other clients, rotation refused, no replacement parent available for same country+format.
schedule_hoursarray<int>Probe schedule used by the system: [1, 6, 12, 24, 72, 168].

Example Request

curl -X POST "https://proxy587.com/api/v1/proxies/parent/rotate" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_ips": ["185.10.20.30"]
  }'

Example Response 200 OK

{
  "status": "success",
  "data": {
    "rotated": [
      {
        "rotation_id": "ROT-20260529-AB12",
        "proxy_ip": "185.10.20.30",
        "status": "active",
        "test_index": 0,
        "schedule_hours": [1, 6, 12, 24, 72, 168],
        "next_test_at": "2026-05-29T23:45:00+00:00",
        "last_tested_at": null,
        "last_test_result": {},
        "created_at": "2026-05-29T22:45:00+00:00",
        "restored_at": null,
        "expired_at": null
      }
    ],
    "errors": [],
    "schedule_hours": [1, 6, 12, 24, 72, 168]
  },
  "errors": []
}
GET /proxies/parent/rotations

List your parent rotation requests (most recent first).

Query Parameters

ParameterTypeDescription
statusstringFilter by status: active, restored, expired, failed.
proxy_ipstringFilter by current proxy IP.
limitintegerDefault 50, max 200.
GET /proxies/parent/rotations/<rotation_id>

Return the current state of a single rotation request.

Status Values

StatusMeaning
activeSystem is still probing the original parent on schedule.
restoredOriginal parent recovered and was automatically restored.
expiredAll 6 probes failed within 7 days; proxy stays on the rotated parent.
failedRotation could not be completed (rare; reserved for system errors).

Example

curl "https://proxy587.com/api/v1/proxies/parent/rotations?status=active&limit=20" \
  -H "Authorization: Bearer your-api-key"
POST /orders/credentials

Set or remove universal login/password credentials for an order.

Request Body

ParameterTypeRequiredDescription
order_idintegerRequiredOrder ID
loginstring|nullRequiredUsername (3-32 chars, alphanumeric)
passwordstring|nullRequiredPassword (6-64 chars)

Set both login and password to null to remove credentials.

Response Fields

FieldTypeDescription
order_idintegerOrder ID
credentials_setbooleanWhether credentials are now set

Example Request

curl -X POST "https://proxy587.com/api/v1/orders/credentials" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": 12345,
    "login": "mylogin",
    "password": "mypassword123"
  }'

Example Response 200 OK

{
  "status": "success",
  "data": {
    "order_id": 12345,
    "credentials_set": true
  },
  "errors": []
}
POST /orders/ip-auth

Set or update IP-based authorization for an order (no login/password needed).

Request Body

ParameterTypeRequiredDescription
order_idintegerRequiredOrder ID
allowed_ipstring|nullRequiredPublic IP to whitelist (or null to remove)

Response Fields

FieldTypeDescription
order_idintegerOrder ID
allowed_ipstring|nullThe whitelisted IP (or null if removed)

Example Request

curl -X POST "https://proxy587.com/api/v1/orders/ip-auth" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": 12345,
    "allowed_ip": "203.0.113.50"
  }'

Example Response 200 OK

{
  "status": "success",
  "data": {
    "order_id": 12345,
    "allowed_ip": "203.0.113.50"
  },
  "errors": []
}
GET /orders/{order_id}/credentials

Get all extra credential pairs for proxies in an order. Extra credentials allow multiple users or services to use the same proxy simultaneously.

Path Parameters

ParameterTypeRequiredDescription
order_idstringRequiredOrder ID

Response Fields

FieldTypeDescription
order_idstringOrder ID
credentialsarrayList of extra credentials
credentials[].idintegerCredential ID
credentials[].order_idstringOrder ID
credentials[].proxy_ipstringAssociated proxy IP
credentials[].usernamestringExtra username
credentials[].passwordstringExtra password
credentials[].labelstringOptional label
credentials[].created_atstringCreation date (ISO 8601)
totalintegerTotal number of credentials

Example Request

curl -X GET "https://proxy587.com/api/v1/orders/ORD-20251129-ABCD/credentials" \
  -H "Authorization: Bearer your-api-key"

Example Response 200 OK

{
  "status": "success",
  "data": {
    "order_id": "ORD-20251129-ABCD",
    "credentials": [
      {
        "id": 1,
        "order_id": "ORD-20251129-ABCD",
        "proxy_ip": "185.10.20.30",
        "username": "extra_user1",
        "password": "extra_pass1",
        "label": "Worker 1",
        "created_at": "2025-11-29T12:00:00Z"
      }
    ],
    "total": 1
  },
  "errors": []
}
POST /orders/extra-credentials

Add extra credential pairs to proxies in an order.

Request Body

ParameterTypeRequiredDescription
order_idstringRequiredOrder ID
countintegerRequiredNumber of credentials per proxy (1-50)
proxy_ipsarrayOptional*Specific proxy IPs to add credentials to
all_proxiesbooleanOptional*Add credentials to all proxies in order
label_prefixstringOptionalLabel prefix for credentials (max 50 chars)

* Either proxy_ips or all_proxies must be provided.

Response Fields

FieldTypeDescription
order_idstringOrder ID
created_countintegerNumber of credentials created
credentialsarrayList of created credentials

Example Request

curl -X POST "https://proxy587.com/api/v1/orders/extra-credentials" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-20251129-ABCD",
    "all_proxies": true,
    "count": 2,
    "label_prefix": "Worker"
  }'

Example Response 200 OK

{
  "status": "success",
  "data": {
    "order_id": "ORD-20251129-ABCD",
    "created_count": 20,
    "credentials": [
      {
        "id": 1,
        "proxy_ip": "185.10.20.30",
        "username": "extra_abc123",
        "password": "pass_xyz789",
        "label": "Worker 1"
      }
    ]
  },
  "errors": []
}
POST /orders/extra-credentials/delete

Delete extra credentials from an order. Can delete specific credentials, all for certain proxies, or all for the order.

Request Body

ParameterTypeRequiredDescription
order_idstringRequiredOrder ID
credential_idsarrayOptional*Specific credential IDs to delete
proxy_ipsarrayOptional*Delete all credentials for these proxies
allbooleanOptional*Delete all extra credentials for the order

* At least one of credential_ids, proxy_ips, or all must be provided.

Response Fields

FieldTypeDescription
order_idstringOrder ID
deleted_countintegerNumber of credentials deleted

Example Request

curl -X POST "https://proxy587.com/api/v1/orders/extra-credentials/delete" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-20251129-ABCD",
    "credential_ids": [1, 2, 3]
  }'

Example Response 200 OK

{
  "status": "success",
  "data": {
    "order_id": "ORD-20251129-ABCD",
    "deleted_count": 3
  },
  "errors": []
}