ProxyMesh API

The ProxyMesh API lets you programmatically manage the following:

The base URL for API calls is https://proxymesh.com. The path for each API call is shown below. Every request must be authenticated using your main parent account credentials. If you have any questions about usage, please contact support.

Sub-Accounts and Limits

Sub-accounts are real accounts that can login to ProxyMesh, but with restricted capabilities. Your account is the parent account, which has complete control over its sub-accounts, including setting monthly or total bandwidth limits. By setting appropriate limits and tracking bandwidth usage, you can bill your sub- accounts based on their bandwidth usage.

Each ProxyMesh subscription plan has different sub-account limits. If you reach your limit, then you will no longer be able to create more sub-accounts, and will instead get a 402 response code. To remedy this, you must either upgrade your plan or delete sub-accounts.

Bandwidth Limits

Note: Bandwidth is measured in gigabytes ("GB").

By default, a sub-account has no limit on bandwidth usage. You can set a monthly_bandwidth_limit and/or a total_bandwidth_limit. When a limit is reached, all future requests to a proxy server will return a 509 error code.

The total_bandwidth_limit applies to all bandwidth used over all time, while the monthly_bandwidth_limit only applies to bandwidth used within your subscription's billing period. For example, if your billing period starts on the 10th of each month, and you set a monthly_bandwidth_limit on a sub-account, then that account reaches its limit before the next 10th of the month, all requests will get a 509 response until the 10th (or you increase their limit). The total_bandwidth_limit does not reset, and must be changed by your manual action.

Your parent account can also have bandwidth limits that you set manually. All sub-account bandwidth usage counts towards your parent account bandwidth usage, so if you set any bandwidth limits on your parent account, and they are reached, then all sub-accounts will get 509 response codes from the proxy servers until your parent bandwidth limits are reset or updated.

Authentication

Every request must be authenticated with HTTP Basic Authorization. This means every request should have a header that looks like this: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==. If the header is not present or the username:password authorization fails, you will get a 401 error code indicating basic authentication failure.

Note that 4 authentication failures in a short period of time will result in a 3-hour ban. To resolve the error, you'll need to correct your Proxy-Authorization header; but to do so you must wait until the ban expires.

Error Codes

A successful request will return a 200 status code. If a request is not successful, then one of the following error codes will be returned to indicate what went wrong.

302

HTTP request when HTTPS is required.

400

Form error, will include JSON error response body.

401

Basic authentication failure. See Authentication for details.

402

Payment required. You will need to upgrade your plan to add more.

403

Forbidden to complete API call. This can happen if you are authenticating as a sub-account, or if you are trying to modify a sub-account that isn't yours.

404

Sub-account not found.

405

Wrong HTTP method.

500

Server error - something went wrong at the ProxyMesh API server.

503

Plan error - unable to lookup subscription plan. Please try again in a few minutes.


Create New Sub-Account

To create new sub-accounts via the API, use the POST request method, which transmits the web form data described below, stored in the body of the request.

Note: All of this API's other requests that are done with the POST method also carry request parameters in the message body, providing a high level of  transmission security.

Because sub-accounts are limited real accounts, it is important to choose appropriate usernames. A best practice would be to prefix all sub-account usernames with a short string that represents your business, such as pm_. Usernames are globally unique, so choosing a unique prefix will reduce the chance of attempting to create an account where the username already exists.

POST /api/sub/create/

  • username Required: up to 30 alphanumeric characters, including .@+-
  • password Optional: up to 128 characters
  • first_name Optional: up to 20 characters
  • last_name Optional: up to 20 characters
  • email Optional: up to 255 characters
  • monthly_limit Optional: positive integer in GBs to restrict monthly bandwidth usage, defaults to 0 (no limit)
  • total_limit Optional: positive integer GBs to restrict total bandwidth usage, defaults to 0 (no limit)

On success, returns sub-account details. Can return the following error codes:

Edit a Sub-Account

Use this API to edit an existing sub-account and/or update bandwidth limits. You can perform the same actions manually by editing sub-accounts from your account dashboard.

POST /api/sub/edit/

Takes all the same parameters as Create Sub-Account. The username field must match one of your existing sub-accounts, otherwise you will get a 403 error code. On success, returns sub-account details. Can return the following error codes:

  • 400 if the form is invalid
  • 403 if username is not a sub-account of yours
  • 404 if the sub-account cannot be found.

Get Sub-Account Details

Use this API request method to lookup sub-account details, including current bandwidth usage and limits.

A well-formed request for sub-account details, via the API's GET method, should look like this:

/api/sub/get/?username=nnnnnnn

where "nnnnnnn" represents the value of the username.

GET /api/sub/get/

  • username Required: the username of a sub-account

On success, returns sub-account details. This is a JSON object with the following fields:

  • username: The username of the sub-account.
  • active: true or false depending on whether the account has been deactivated.
  • monthly_bandwidth: The bandwidth (in GB) used by this sub-account in your current billing period.
  • monthly_bandwidth_limit: The monthly bandwidth limit for this sub-account, default is 0.
  • total_bandwidth: The total bandwidth used by this sub-account. Will always be equal to or greater than monthly_bandwidth.
  • total_bandwidth_limit: The total bandwidth limit for this sub-account, default is 0.

The following fields are optional and will only be present if previously set when creating or editing the sub-account:

  • first_name: First name for the sub-account.
  • last_name: Last name for the sub-account.
  • email: Email address for the sub-account.

Deactivate a Sub-Account

Deactivating a sub-account will cause all proxy requests for that sub-account to return a 402 error code. You should deactivate a sub-account when they are behind on payment, or have cancelled their account with you but might re-activate in the future. If they update their payment information or re-activate their account with you, then you can reactivate their sub-account.

POST /api/sub/deactivate/

  • username Required: the username of a sub-account

On success, returns sub-account details.

Activate a Sub-Account

All sub-accounts are active by default, so this API call is only useful for sub-accounts that have been previously deactivated.

POST /api/sub/activate/

  • username Required: the username of a sub-account

On success, returns sub-account details.

Delete a Sub-Account

This will permanently delete a sub-account, and all associated data will be gone forever. It is recommended that you deactivate accounts first, then only delete a sub-account if you are sure you will never need it again and/or have hit your sub-account limits.

POST /api/sub/delete/

  • username Required: the username of a sub-account

Returns an empty 200 response on success.


Add Authenticated IP

Add an IP address to your list of authenticated IP addresses. IPs are added to your main account, unless you provide a sub-account username. There is no limit on authenticated IPs.

POST /api/ip/add/

  • ip Required: the IP address to add
  • username Optional: the username of a sub-account to add the IP to

Returns a 200 response on success, containing a JSON object that looks like {"ip": IP}. A 400 response is returned if the ip is already authenticated.

Delete Authenticated IP

Delete an IP address from your list of authenticated IP addresses. You can also delete from a sub-account by providing the sub-account username.

POST /api/ip/delete/

  • ip Required: the IP address to delete
  • username Optional: the username of a sub-account to delete the IP from

Returns an empty 204 response on success. A 400 response is returned if the ip is not already authenticated.

List Authenticated IPs

Get a list of your authenticated IP addresses.

GET /api/ips/

  • username Optional: the username of a sub-account to list IPs from

Returns a JSON object with an ips field that will be a list of your authenticated IP addresses. It will be an empty list if you have no authenticated IP addresses.

{"ips": ["IP"]}

Add Authenticated Hostname

Add a hostname to your list of authenticated hostnames. Hostnames are added to your main account, unless you provide a sub-account username.

POST /api/hostname/add/

  • domain Required: the hostname to add
  • username Optional: the username of a sub-account to add the domain to

Returns a 200 response on success, containing a JSON object that looks like {"domain": domain}. A 400 response is returned if the domain is already authenticated.

Delete Authenticated Hostname

Delete a hostname from your list of authenticated hostnames. You can also delete from a sub-account by providing the sub-account username.

POST /api/hostname/delete/

  • domain Required: the hostname to delete
  • username Optional: the username of a sub-account to delete the hostname from

Returns an empty 204 response on success. A 400 response is returned if the domain is not already authenticated.

List Authenticated Hostnames

Get a list of your authenticated hostnames.

GET /api/hostnames/

  • username Optional: the username of a sub-account to list hostnames from

Returns a JSON object with a  domains field that will be a list of your authenticated hostnames. It will be an empty list of you have no authenticated domains.

{"domains": ["DOMAIN"]}

Get Authorized Proxies

Returns a list of the proxies that you have access to. You can use this to show your sub-account customers the proxy hosts they can access.

GET /api/proxies/

Returns a JSON object with a proxies field that looks like this:

{"proxies": ["DOMAIN:PORT"]}

The list of proxies will contain all the ProxyMesh proxies your parent account has access to.

Add Proxy Authorization

Add authorization for a proxy server. If you already have authorization for that proxy, nothing will change.

POST /api/proxy/add/

  • proxy Required: the hostname of the proxy server. This can be just the host, such as proxy-host, the full domain, such as proxy-host.proxymesh.com, or even domain:port, such as host.proxymesh.com:31280.

Returns a JSON object that containing the full domain of the proxy, as in:

{"proxy": "proxy-host.proxymesh.com"}

Returns a 402 response if your subscription plan does not allow adding any more proxies. A 400 response is returned if proxy is not recognized. If a 503 response is returned, then there was a problem looking up your plan, and you should try again in a few minutes.

Delete Proxy Authorization

Remove authorization for a proxy server. If you do not already have authorization for that proxy, nothing will change.

POST /api/proxy/delete/

  • proxy Required: the hostname of the proxy server. This can be just the host, such as proxy-host, the full domain, such as proxy-host.proxymesh.com, or even domain:port, such as proxy-host.proxymesh.com:31280.

Returns an empty 204 response on success. A 400 response is returned if proxy is not recognized.


Geo IPs

The open and world proxies have IPs around the world, but you can use the X-ProxyMesh-Country header if you only want to use IPs from a certain country. These API methods give you a way to programmatically get the supported ISO country codes and IP counts for either the open or world proxy servers. Both API methods return a JSON object that looks like:

{"CODE": count}

GET /api/geoips/open/

Returns a JSON object with  ISO country codes and IP counts for the open proxy.

GET /api/geoips/world/

Returns a JSON object with  ISO country codes and IP counts for the world proxy.

Still need help? Contact Us Contact Us