ProxyMesh API

The ProxyMesh API lets you programmatically manage the following:

• sub-accounts
• authorized IP addresses and hostnames
• authorized proxies
• geo IPs

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

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

• 400

• 401

• 402

• 403

• 404

• 405

• 500

• 503

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)

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

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

• 400 if the form is invalid
• 402 if you have hit your sub-account limits.

Note: You can also create sub-accounts from your dashboard. Click here for details.

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/

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

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. Includes fractions of a GB.
• 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

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

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

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

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

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

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 the account you are authenticating with, unless you provide a sub-account username and are authenticating with your parent account. There is a limit of 100 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
• label Optional: label to attach the IP address

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

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. A 403 error is returned if you pass a sub account username and you are not authenticating as the parent account.

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 , if you are authenticating as the parent account.

POST /api/ip/delete/

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

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

Returns an empty 204 response on success. A 400 response is returned if the ip is not already authenticated. A 403 error is returned if you pass a sub account username and you are not authenticating as the parent account.

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"]}

List Authenticated IP with Labels

Get a list of your authenticated IP addresses with attached labels.

GET /api/ip_labels/

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

Returns a JSON object with a list of your authenticated IP addresses & labels. It will be an empty list if you have no authenticated IP addresses. If an IP address does not have a label, then the label will be an empty string.

[{"ip": "IP", "label": "LABEL"}]

Add Authenticated Hostname

Add a hostname to your list of authenticated hostnames. Hostnames are added to the authenticating account, unless you provide a sub-account username and are authenticating as the parent account.

POST /api/hostname/add/

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

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

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. A 403 error is returned if you pass a sub account username and you are not authenticating as the parent account.

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 and are authenticating as the parent account.

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. A 403 error is returned if you pass a sub account username and you are not authenticating as the parent account.

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. You can also use it to get your list of authorized proxies into your own scripts.

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 .

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

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 .

Note: Please make sure you are sending form-encoded data, not JSON. Otherwise you will get an error message.

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.