ProxyMesh API

The ProxyMesh API lets you programmatically manage the following:

• sub-accounts
• authorized IP addresses and hostnames
• authorized proxies
• bearer tokens
• 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 using one of the following methods:

• HTTP Basic Authorization — send Authorization: Basic …   with your parent account username:password  .
• Bearer token — send Authorization: Bearer pm_…   with a token you created in the dashboard or API. See Bearer Token Authentication.

If authentication fails, you receive 401  . Four authentication failures in a short period result in a 3-hour ban. To resolve a ban, correct your Authorization   header and wait until the ban expires.

Exception: Bearer token management endpoints (Bearer Tokens) require HTTP Basic Authorization only. Bearer tokens cannot be used to create, list, activate, deactivate, or delete other tokens.

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.

Bearer Tokens

Create and manage bearer tokens on paid plans.

All bearer token endpoints require HTTP Basic Authorization with your parent account credentials. To manage tokens for a sub-account, authenticate as the parent and pass username   (sub-account name) as noted below.

GET /api/tokens/

• username   Optional: sub-account username to list tokens for

Returns a JSON object with a tokens   array. Each entry includes id  , label  , is_active  , expires_at  , and created_at  . The raw token secret is never returned after creation.

{"tokens": [{"id": 1, "label": "production", "is_active": true, "expires_at": null, "created_at": "2026-01-15T12:00:00"}]}

POST /api/token/create/

• label   Optional: up to 100 characters
• expires_at   Optional: expiration date (YYYY-MM-DD  ); blank means no expiration

Note: Please make sure you are sending form-encoded data, not JSON.

On success, returns token metadata plus the raw token   value once. Can return 402   if your plan does not support bearer tokens or you have reached your token limit.

{"id": 1, "label": "production", "token": "pm_…", "is_active": true, "expires_at": null, "created_at": "2026-01-15T12:00:00"}

POST /api/token/deactivate/

• id   Required: token ID

Deactivates the token. Returns updated token metadata on success.

POST /api/token/activate/

• id   Required: token ID

Reactivates a previously deactivated token. Cannot activate an expired token.

POST /api/token/delete/

• id   Required: token ID

Permanently deletes the token. Returns an empty 204   response on success.

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.