Proxy Management API

The Proxy Management API provides a suite of endpoints for retrieving, assigning, updating, testing, and managing proxy configurations associated with OnlyFans accounts. This is crucial for ensuring consistent IP addresses between user browsing sessions (via the Chrome extension) and backend scraping tasks.

Base URLs

API requests can be made to the following base URLs depending on the environment:

Production: https://onlyautomator.com
Local Web App: http://localhost:3000
Local Microservice: http://localhost:3001

Authentication

All proxy management endpoints require authentication using a Bearer Token (JWT obtained after login) passed in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Endpoints Overview

Get Account Proxy Config

Retrieve the current proxy setup for a specific account.

Assign Automatic Proxy

Automatically assign a suitable Webshare proxy to an account.

Set Manual Proxy

Manually configure a specific proxy provided by the user.

Set Preferences

Update preferences like preferred region or activation status.

Disable Proxy

Turn off proxy usage for a specific account.

Handle Failure

Report a failing proxy and optionally trigger auto-reassignment.

Test Proxy Connectivity

Test the connection of a given proxy configuration without saving it.

Get Available Proxies (Webshare)

List available proxies directly from Webshare (Admin/Internal).

Get Available Countries (Webshare)

List countries where Webshare proxies are available.

Get Available Cities (Webshare)

List cities within a country where Webshare proxies are available.

Get Client IP

Utility endpoint to check the client’s current external IP address.

Endpoints Details

Get Account Proxy Configuration

GET /api/proxy/account/{accountId}

Retrieves the currently stored proxy configuration details for a specific OnlyFans account.

Path Parameters

Parameter	Type	Description
`accountId`	string	The unique identifier (UUID) of the account.

Successful Response (200 OK)

Returns the proxy details associated with the account.

Mock Response

{
  "success": true,
  "data": {
    "proxy_id": "ws_proxy_12345abcde",
    "proxy_address": "185.123.101.234",
    "proxy_port": 8080,
    "proxy_username": "username123",
    // Note: proxy_password is NOT returned
    "proxy_country_code": "US",
    "proxy_city_name": "New York",
    "proxy_assigned_at": "2023-09-15T14:32:45Z",
    "proxy_mode": "auto",
    "proxy_is_active": true,
    "proxy_region_preference": "US",
    "proxy_city_preference": "New York"
  }
}

Error Responses

401 Unauthorized: Invalid or missing authentication token.
404 Not Found: The specified accountId does not exist.
500 Internal Server Error: Unexpected server issue.

Assign Automatic Proxy

POST /api/proxy/account/{accountId}/assign-auto

Automatically selects an available, suitable proxy from the Webshare pool and assigns it to the specified account. This is the recommended method for most users.

Path Parameters

Parameter	Type	Description
`accountId`	string	The unique identifier (UUID) of the account.

Request Body (Optional)

You can optionally provide preferences for the automatic assignment:

Request Body

{
  "preferredCountry": "DE",
  "preferredCity": "Berlin",
  "forceReassign": false 
}

preferredCountry (string, optional): ISO 3166-1 alpha-2 code (e.g., “DE”, “US”).
preferredCity (string, optional): City name within the preferred country.
forceReassign (boolean, optional, default: false): If true, any existing proxy configuration will be replaced. If false, the assignment will fail if a proxy is already assigned (unless it was inactive or failed).

Successful Response (200 OK)

Returns the details of the newly assigned proxy.

Mock Response

{
  "success": true,
  "message": "Proxy assigned successfully",
  "data": {
    "proxy_id": "ws_proxy_new123",
    "proxy_address": "88.198.15.100",
    "proxy_port": 8080,
    "proxy_username": "webshare_user",
    "proxy_country_code": "DE",
    "proxy_city_name": "Berlin",
    "proxy_assigned_at": "2024-07-27T10:00:00Z",
    "proxy_mode": "auto"
  }
}

Error Responses

400 Bad Request: Invalid request body format.
401 Unauthorized: Invalid or missing authentication token.
404 Not Found: The specified accountId does not exist.
409 Conflict: Cannot assign proxy (e.g., proxy already assigned and forceReassign is false, or account is in manual mode).
503 Service Unavailable: No suitable proxies were found in the Webshare pool matching the criteria.
500 Internal Server Error: Unexpected server issue.

Set Manual Proxy

POST /api/proxy/account/{accountId}/set-manual

Allows the user to manually specify a proxy configuration. The system attempts to test the connectivity of the provided proxy before saving it.

Path Parameters

Parameter	Type	Description
`accountId`	string	The unique identifier (UUID) of the account.

Request Body (Required)

Request Body

{
  "proxy_address": "your.proxy.hostname",
  "proxy_port": 9999,
  "proxy_username": "yourProxyUser",
  "proxy_password": "yourProxyPass",
  "proxy_country_code": "GB", // Optional, for display
  "proxy_city_name": "London" // Optional, for display
}

proxy_address (string, required): IP address or hostname.
proxy_port (integer, required): Port number.
proxy_username (string, optional): Required if proxy needs authentication.
proxy_password (string, optional): Required if proxy needs authentication.
proxy_country_code (string, optional): User-provided country code (not validated by system).
proxy_city_name (string, optional): User-provided city name.

Successful Response (200 OK)

Indicates the manual proxy was successfully tested and saved.

Mock Response

{
  "success": true,
  "message": "Manual proxy configured successfully",
  "data": {
    "proxy_address": "your.proxy.hostname",
    "proxy_port": 9999,
    "proxy_username": "yourProxyUser",
    "proxy_country_code": "GB",
    "proxy_city_name": "London",
    "proxy_mode": "manual",
    "proxy_assigned_at": "2024-07-27T10:05:00Z",
    "proxy_is_active": true
  }
}

Error Responses

400 Bad Request:
- Invalid request body format (missing required fields).
- Proxy connectivity test failed (error message will specify this).
401 Unauthorized: Invalid or missing authentication token.
404 Not Found: The specified accountId does not exist.
500 Internal Server Error: Unexpected server issue during testing or saving.

Set Proxy Preferences

PUT /api/proxy/account/{accountId}/preference

Updates preferences related to proxy usage for an account, such as the preferred region for automatic assignments or whether the proxy configuration is currently active. This does not change the currently assigned proxy itself.

Path Parameters

Parameter	Type	Description
`accountId`	string	The unique identifier (UUID) of the account.

Request Body (Required - at least one property)

Request Body

{
  "proxy_region_preference": "DE", 
  "proxy_city_preference": "Frankfurt",
  "proxy_is_active": true
}

proxy_region_preference (string, nullable): Preferred ISO country code (e.g., “DE”, “US”). Set to null or omit to remove preference.
proxy_city_preference (string, nullable): Preferred city within the region. Set to null or omit to remove preference.
proxy_is_active (boolean, optional): Set to false to temporarily disable using the assigned proxy, true to enable.

Successful Response (200 OK)

Confirms the preferences were updated.

Mock Response

{
  "success": true,
  "message": "Proxy preferences updated successfully",
  "data": {
    "proxy_region_preference": "DE",
    "proxy_city_preference": "Frankfurt",
    "proxy_is_active": true
  }
}

Error Responses

400 Bad Request: Invalid request body format (e.g., empty object).
401 Unauthorized: Invalid or missing authentication token.
404 Not Found: The specified accountId does not exist.
500 Internal Server Error: Unexpected server issue.

Disable Proxy

POST /api/proxy/account/{accountId}/disable

Disables proxy usage for the specified account by setting its mode to none and marking it as inactive. Any previously assigned proxy details might be cleared or simply ignored.

Path Parameters

Parameter	Type	Description
`accountId`	string	The unique identifier (UUID) of the account.

Successful Response (200 OK)

Confirms the proxy was disabled.

Mock Response

{
  "success": true,
  "message": "Proxy disabled successfully",
  "data": {
    "proxy_mode": "none",
    "proxy_is_active": false,
    "proxy_id": null,
    "proxy_address": null,
    "proxy_port": null,
    "proxy_username": null,
    "proxy_country_code": null,
    "proxy_city_name": null,
    "proxy_assigned_at": null
  }
}

Error Responses

401 Unauthorized: Invalid or missing authentication token.
404 Not Found: The specified accountId does not exist.
500 Internal Server Error: Unexpected server issue.

Handle Proxy Failure

POST /api/proxy/account/{accountId}/handle-failure

Used to report that the currently assigned proxy for an account has failed (e.g., connection error, blocked). This endpoint can log the failure and, if the account is in auto mode, optionally attempt to automatically assign a new proxy.

Path Parameters

Parameter	Type	Description
`accountId`	string	The unique identifier (UUID) of the account.

Request Body (Optional)

Request Body

{
  "error": "ECONNRESET",
  "autoReassign": true
}

error (string, optional): Description of the error encountered.
autoReassign (boolean, optional, default: true): If true and the account’s proxy_mode is auto, the system will attempt to assign a new proxy. Ignored if mode is manual or none.

Successful Response (200 OK)

Indicates the failure was processed. Includes details about whether reassignment was attempted and successful.

Mock Response (Reassignment Successful)

{
  "success": true,
  "message": "Proxy failure handled. New proxy assigned.",
  "data": {
    "reassigned": true,
    "new_proxy_info": {
      "proxy_id": "ws_proxy_new67890",
      "proxy_address": "93.184.216.34",
      "proxy_port": 8080,
      "proxy_country_code": "GB",
      "proxy_city_name": "London"
    }
  },
  "error": null
}

Mock Response (Reassignment Failed or Not Attempted)

{
  "success": true,
  "message": "Proxy failure handled. Reassignment not performed or failed.",
  "data": {
    "reassigned": false,
    "new_proxy_info": null
  },
  "error": "Failed to reassign proxy: No suitable automatic proxy found." // Example error if applicable
}

Error Responses

400 Bad Request: Invalid request body format.
401 Unauthorized: Invalid or missing authentication token.
404 Not Found: The specified accountId does not exist.
503 Service Unavailable: Reassignment attempted but failed due to lack of available proxies.
500 Internal Server Error: Unexpected server issue.

Test Proxy Connectivity

POST /api/proxy/test-connectivity

Tests the connectivity of a proxy configuration provided in the request body. This does not save the configuration to any account; it’s purely for testing.

Request Body (Required)

Request Body

{
  "proxy_address": "test.proxy.com",
  "proxy_port": 8000,
  "proxy_username": "testUser",
  "proxy_password": "testPassword"
    }

proxy_address (string, required)
proxy_port (integer, required)
proxy_username (string, optional)
proxy_password (string, optional)

Successful Response (200 OK)

Indicates the provided proxy details allowed a successful connection test.

Mock Response

{
  "success": true,
  "message": "Proxy connection test successful.",
  "tested_proxy": {
    "address": "test.proxy.com",
    "port": 8000,
    "username_provided": true
  }
}

Error Responses

400 Bad Request:
- Invalid request body format.
- Proxy connectivity test failed (error message will specify the reason).
401 Unauthorized: Invalid or missing authentication token.
500 Internal Server Error: Unexpected server issue during the test.

Get Available Webshare Proxies (Admin/Internal)

GET /api/proxy/webshare/available

Retrieves a list of available proxies directly from the configured Webshare API pool. Intended primarily for internal system use or administrative panels. Requires specific permissions.

Query Parameters

Parameter	Type	Description
`country_code__in`	string	Optional. Comma-separated list of ISO country codes (e.g., “DE,US”).
`page_size`	integer	Optional. Max proxies per page (default: 100).
`page`	integer	Optional. Page number for pagination (default: 1).

Successful Response (200 OK)

Returns a list of proxies matching the Webshare API response structure.

Mock Response

{
  "count": 150,
  "next": "https://proxy.webshare.io/api/v2/proxy/list/?page=2",
  "previous": null,
  "results": [
    {
      "id": "f1c2d3e4-abcd-1234-wxyz-567890abcdef",
      "username": "webshare_user",
      "password": "webshare_pass", // Note: Sensitive
      "proxy_address": "1.2.3.4",
      "port": 8080,
      "valid": true,
      "last_verification": "2023-09-16T12:00:00Z",
      "country_code": "DE",
      "city_name": "Berlin",
      "asn": { "asn": 12345, "name": "Example ISP" }
    }
    // ... more results
  ]
}

Error Responses

401 Unauthorized: Missing or invalid token/insufficient permissions.
503 Service Unavailable: Could not connect to or retrieve data from the Webshare API.
500 Internal Server Error: Unexpected server issue.

Get Available Proxy Countries

GET /api/proxy/webshare/available-countries

Retrieves a list of countries where Webshare proxies are known to be available, potentially grouped by region. Useful for populating dropdowns in the UI.

Successful Response (200 OK)

Mock Response

{
  "success": true,
  "data": [
    { "code": "US", "name": "United States", "region": "North America" },
    { "code": "DE", "name": "Germany", "region": "Europe" },
    { "code": "GB", "name": "United Kingdom", "region": "Europe" }
    // ... more countries
  ]
}

Error Responses

401 Unauthorized: Invalid or missing authentication token.
503 Service Unavailable: Failed to retrieve country list from cache or source.
500 Internal Server Error: Unexpected server issue.

Get Available Proxy Cities by Country

GET /api/proxy/webshare/available-cities

Retrieves a list of cities within a specified country where Webshare proxies are known to be available.

Query Parameters

Parameter	Type	Description
`countryCode`	string	Required. ISO 3166-1 alpha-2 code (e.g., “DE”).

Successful Response (200 OK)

Mock Response (for countryCode=DE)

{
  "success": true,
  "data": [
    { "name": "Berlin" },
    { "name": "Frankfurt" }
    // ... more cities for the country
  ]
}

Error Responses

400 Bad Request: Missing or invalid countryCode parameter.
401 Unauthorized: Invalid or missing authentication token.
404 Not Found: No cities found for the specified valid countryCode (or country not supported).
503 Service Unavailable: Failed to retrieve city list from cache or source.
500 Internal Server Error: Unexpected server issue.

Get Client IP

GET /api/whatsmyip

Utility endpoint that returns the IP address of the client making the request, as seen by the server. Useful for verifying if a proxy connection is active from the client-side.

Successful Response (200 OK)

Mock Response

{
  "ip": "192.0.2.1",
  "country": "US" // Country is optional, based on IP geolocation
}

Error Responses

500 Internal Server Error: Unexpected server issue retrieving IP.

Standard Error Responses

Most errors return a JSON body conforming to the ErrorResponse schema defined in the OpenAPI specification:

Error Response Schema

{
  "success": false, 
  "error": "Human-readable error message",
  "code": "OPTIONAL_ERROR_CODE", 
  "details": { /* Optional details */ }
}

Refer to the specific endpoint documentation above for common 4xx and 5xx status codes.

Integration Examples

(Examples provided previously remain largely relevant, ensure API tokens and account IDs are placeholders)

Best Practices

Security: Protect your API tokens. Do not embed them directly in client-side code distributed to users.
Error Handling: Check HTTP status codes and parse the JSON error response for details.
Idempotency: Be mindful that some operations (like auto-assignment without forceReassign) might fail if repeated under certain conditions (e.g., proxy already assigned).
Consistency: Try to use the automatically assigned proxies (auto mode) for best results, as these are managed and rotated by the system.
Testing: Use /api/proxy/test-connectivity to validate manual configurations, and /api/whatsmyip from the client to confirm the proxy is active in the browser/application.

Overview

Account & Auth

Extension API (v2)

Fan API

Emoji API

Scripts API

Marketing API

Automated Tasks (Cron)

Webhooks

Microservice API

Database API (Supabase)

Testing API

​Base URLs

​Authentication

​Endpoints Overview

Get Account Proxy Config

Assign Automatic Proxy

Set Manual Proxy

Set Preferences

Disable Proxy

Handle Failure

Test Proxy Connectivity

Get Available Proxies (Webshare)

Get Available Countries (Webshare)

Get Available Cities (Webshare)

Get Client IP

​Endpoints Details

​Get Account Proxy Configuration

​Path Parameters

​Successful Response (200 OK)

​Error Responses

​Assign Automatic Proxy

​Path Parameters

​Request Body (Optional)

​Successful Response (200 OK)

​Error Responses

​Set Manual Proxy

​Path Parameters

​Request Body (Required)

​Successful Response (200 OK)

​Error Responses

​Set Proxy Preferences

​Path Parameters

​Request Body (Required - at least one property)

​Successful Response (200 OK)

​Error Responses

​Disable Proxy

​Path Parameters

​Successful Response (200 OK)

​Error Responses

​Handle Proxy Failure

​Path Parameters

​Request Body (Optional)

​Successful Response (200 OK)

​Error Responses

​Test Proxy Connectivity

​Request Body (Required)

​Successful Response (200 OK)

​Error Responses

​Get Available Webshare Proxies (Admin/Internal)

​Query Parameters

​Successful Response (200 OK)

​Error Responses

​Get Available Proxy Countries

​Successful Response (200 OK)

​Error Responses

​Get Available Proxy Cities by Country

​Query Parameters

​Successful Response (200 OK)

​Error Responses

​Get Client IP

​Successful Response (200 OK)

​Error Responses

​Standard Error Responses

​Integration Examples

​Best Practices

Base URLs

Authentication

Endpoints Overview

Endpoints Details

Get Account Proxy Configuration

Path Parameters

Successful Response (200 OK)

Error Responses

Assign Automatic Proxy

Path Parameters

Request Body (Optional)

Successful Response (200 OK)

Error Responses

Set Manual Proxy

Path Parameters

Request Body (Required)

Successful Response (200 OK)

Error Responses

Set Proxy Preferences

Path Parameters

Request Body (Required - at least one property)

Successful Response (200 OK)

Error Responses

Disable Proxy

Path Parameters

Successful Response (200 OK)

Error Responses

Handle Proxy Failure

Path Parameters

Request Body (Optional)

Successful Response (200 OK)

Error Responses

Test Proxy Connectivity

Request Body (Required)

Successful Response (200 OK)

Error Responses

Get Available Webshare Proxies (Admin/Internal)

Query Parameters

Successful Response (200 OK)

Error Responses

Get Available Proxy Countries

Successful Response (200 OK)

Error Responses

Get Available Proxy Cities by Country

Query Parameters

Successful Response (200 OK)

Error Responses

Get Client IP

Successful Response (200 OK)

Error Responses

Standard Error Responses

Integration Examples

Best Practices