SuperNova Proxy SuperNova
Login Register →

Developer API Documentation

Use our API to make your life better or for resale purposes

Developer API Documentation

Your service allows you to work with us via API. It may be useful when your software supports API or if you want to re-distribute our proxies under your brand or via your shop. First of all, login in your account and on top of this page you will find form to create API key. API key is used for all requests to our API. You are allowed to have only one API key. You may refresh your API key at any moment, old ones will be disabled automatically.

Recommendations:

1. Update countries, states/regions and cities at least 1 time per minute or before proxy link creation or updates

2. Link formats updates very rare. Please contact support if you need special proxy link format

3. Do not ignore subaccount limits! If you sell proxy links somewhere, always set limits or you may lost your funds from your account balance!

4. You may use your domain name for client connections instead of ours: just ping our connections gateway domain, get our current IP address and update your DNS records to pin our IP. We support only IPv4 incoming connection addresses and drop IPv6 connections. Please contact support if you need assistance.

General Information

You must add your API key to request header: 

Content-Type: application/json
Authorization: ApiKey 00000000-0000-0000-0000-000000000000

Errors will have HTTP code, short description and always 'success'=false flag:

{
  "data": {
    "general": "API key not recognized or user is blocked"
  },
  "success": false
}

Rate limiting applied to all API endpoints for your security. Do not request them too often otherwise you will receive 429 Error code. If you need more requests, please contact our support. In response header you will see remaining requests before 429 error:

< X-Ratelimit-Limit: 5
< X-Ratelimit-Remaining: 4
< X-Ratelimit-Reset: 15

Account balance

Request to get your current account balance:

curl -X GET https://supernovanet.org/api/v1/balance -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" ### Get Balance
GET https://supernovanet.org/api/v1/balance
Authorization: ApiKey 00000000-0000-0000-0000-000000000000

Successful response on request will be:

HTTP/1.1 200 OK
Date: Thu, 01 Apr 2025 00:00:00 GMT
Content-Type: application/json
Content-Length: 73
X-Ratelimit-Limit: 5
X-Ratelimit-Remaining: 4
X-Ratelimit-Reset: 15
Connection: close

{
  "data": {
    "balance_string": "$14.97",
    "balance_float": 14.97
  },
  "success": true
}

Available countries

Request to get available countries. Please pay attention that in that list presented countries of all proxies regardless of their types. This is equal setting to select all proxy types. You can not filter countries by types.

curl -X GET https://supernovanet.org/api/v1/inventory/countries -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

Successful response on request will be:

{
    "data": [{
        "name": "France",
        "iso": "FR"
    }, 
    ... // More countries in the list
    {
        "name": "Latvia",
        "iso": "LV"
    }],
    "success": true
}

Available States/Regions and Countries

Request to get available states from selected country. Please pay attention that in that list presented regions and cities of all proxies regardless of their types (Mobile, Residential, Mixed). This is equal setting to select all proxy types. You can not filter by types of proxies available. You will get error if you will not specify country. You will always receive all States/Regions in selected Country

curl -X GET "https://supernovanet.org/api/v1/inventory/targeting?country=US" -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

You may filter Cities in selected state by specifying State ID:

curl -X GET "https://supernovanet.org/api/v1/inventory/targeting?country=US&state=4361885" -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

Successful response on request will be:

{
    "data": {
        "states": [{
                "name": "Maryland",
                "id": 4361885
            },
            ... // More states
            {
                "name": "Illinois",
                "id": 4896861
            }
        ],
        "cities": [{
                "name": "Kissimmee",
                "id": 4160983
            },
            ... // More cities
            {
                "name": "Ellsworth",
                "id": 4963692
            }
        ]
    },
    "success": true
}

Proxy Link Formats

Request to get available proxy link formats (you will need id of format to generate links later!)

curl -X GET https://supernovanet.org/api/v1/formats -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

Successful response on request will be:

{
    "data": [{
        "id": 1,
        "name": "login:pass@host:port",
        "description": "No scheme: login:pass@host:port",
        "format": "{login}:{password}@{host}:{port}"
    }, 
    ... // More formats in the list
    {
        "id": 2,
        "name": "login:pass@ip:port",
        "description": "No scheme: login:pass@ip:port",
        "format": "{login}:{password}@{ip}:{port}"
    }],
    "success": true
}

Active Subaccounts

You may think about subaccount as about user in your system. Subaccounts can be active or archived. They may have limits by date, amount spend and traffic. Subaccount is main entity in our system to track stats.

You must avoid to use one subaccount for different users, as they are sharing connection password and all limits!

To get list of active subaccounts please make that request. You may specify optional parameters p (page) and l (limit) per page. Pagination is enabled by default. Maximum size of elements per request (l) is 300.

curl -X GET "https://supernovanet.org/api/v1/subaccounts/active?p=1&l=30" -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

Successful response on request will be:

{
    "data": {
        "limit": 30,
        "page": 1,
        "total_rows": 1,
        "total_pages": 1,
        "rows": [{
            "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // Main identificator of your Subaccount
            "name": "My List №1",
            "total_traffic": 0, // In Bytes
            "total_spend": 0, // In Dollars
            "status": 1, // See below 
            "amount_limit": 123, // In Dollars
            "traffic_limit": 1, // In Gigabytes
            "date_limit": "2025-04-20T00:00:00+00:00",
            "last_bytes_at": null,
            "created_at": "2025-04-16T17:35:13.313+00:00"
        }]
    },
    "success": true
}

Statuses of subaccounts are:


WORKING = 0
PAUSED = 1
PAUSED DUE TO SUBACCOUNT LIMITS = 2
PAUSED DUE TO NO FUNDS = 3

Archived Subaccounts

You may put subaccounts to archive if they are not required anymore. To get list of archived subaccounts please make that request. You may specify optional parameters p (page) and l (limit) per page. Pagination is enabled by default. Maximum size of elements per request (l) is 300.

curl -X GET "https://supernovanet.org/api/v1/subaccounts/archived?p=1&l=30" -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000"

Successful response on request will be:

{
    "data": {
        "limit": 30,
        "page": 1,
        "total_rows": 1,
        "total_pages": 1,
        "rows": [{
            "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // Main identificator of your Subaccount
            "name": "My List №1",
            "total_traffic": 0, 
            "total_spend": 0, 
            "status": 1, // Status automatically set to Paused when you archive your subaccount!
            "amount_limit": 123, 
            "traffic_limit": 1,
            "date_limit": "2025-04-20T00:00:00+00:00",
            "last_bytes_at": null,
            "created_at": "2025-04-10T17:35:13.313+00:00",
            "archived_at":"2025-04-16T18:20:44.024+00:00" // Pay attention to new field in archived
        }]
    },
    "success": true
}

Successful response on request will be:

You may add subaccount together with limits and password. If you do not specify password, it will be generated by our system

Always set limits if you resale our proxies!

curl -X POST https://supernovanet.org/api/v1/subaccounts/add \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" \
  -d '{
    "name": "Test Subaccount",
    "password": "testpassword123",
    "amount_limit": 100.0,
    "traffic_limit": 1024.0,
    "date_limit": "2025-12-31"
  }'
Please find below description of each request fields:
{
  "name": "Test Subaccount", // Name of your Subaccount (for your convenience)
  "password": "testpassword123", // Password. Leave it blank and we will generate it by our own
  "amount_limit": 100.0, // Amount in US dollars after this subaccount will be stopped
  "traffic_limit": 1024.0, // Amount in Gigabytes after this subaccount will be stopped
  "date_limit": "2025-12-31" // Date after this subaccount will be stopped (last working date)
}'

Successful response on request will be:

{
  "data": {
    "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // This identificator will be required to edit port later!
    "password": "testpassword123",
    "name": "Test Subaccount",
    "total_traffic": 0,
    "total_spend": 0,
    "status": 0,
    "amount_limit": 100,
    "traffic_limit": 1024,
    "date_limit": "2025-12-31T00:00:00+00:00",
    "last_bytes_at": null,
    "created_at": "2025-04-01T12:00:00.000+00:00"
  },
  "success": true
}

Edit Subaccount (List or Port)

To edit your subaccount you need to have Port identificator! Request is the same, but only add port field

If you do not specify 'port' field then new subaccount will be generated!

curl -X POST https://supernovanet.org/api/v1/subaccounts/edit \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" \
  -d '{
    "port": "YOUR_SUBACCOUNT_IDENTIFICATOR",
    "name": "Test Subaccount",
    "password": "testpassword123",
    "amount_limit": 100.0,
    "traffic_limit": 1024.0,
    "date_limit": "2025-12-31"
  }'
Please find below description of each request fields:
{
  "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // Identificator of your Subaccount. Mandatory field for edit subaccount.
  "name": "Test Subaccount", // Name of your Subaccount (for your convenience)
  "password": "testpassword123", // Password. Leave it blank and we will generate it by our own
  "amount_limit": 100.0, // Amount in US dollars after this subaccount will be stopped
  "traffic_limit": 1024.0, // Amount in Gigabytes after this subaccount will be stopped
  "date_limit": "2025-12-31" // Date after this subaccount will be stopped (last working date)
}'

Successful response on request will be:

{
  "data": {
    "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // This identificator will be required to edit port later!
    "password": "testpassword123",
    "name": "Test Subaccount",
    "total_traffic": 0,
    "total_spend": 0,
    "status": 0,
    "amount_limit": 100,
    "traffic_limit": 1024,
    "date_limit": "2025-12-31T00:00:00+00:00",
    "last_bytes_at": null,
    "created_at": "2025-04-01T12:00:00.000+00:00"
  },
  "success": true
}

Start, Stop, Archive and restore from Archive

You may manage status of your subaccount and this immediately will stop or start it from working as proxy.

curl -X POST https://supernovanet.org/api/v1/subaccounts/command \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" \
  -d '{
    "port": "YOUR_SUBACCOUNT_IDENTIFICATOR",
    "command": "start"
  }'
Please find below description of each request fields:
{
  "port": "YOUR_SUBACCOUNT_IDENTIFICATOR", // Identificator of your Subaccount. Mandatory field for edit subaccount.
  "command": "start" // Possible values of command: 'archive' 'restore' 'pause' 'start'
}'

Successful response on request will be:

{
  "data": "ok",
  "success": true
}

Generate proxy connection links

To generate proxy connection links, you have to specify your subaccount, link type, quantity of links (up to 10000), rotattion type, country (mandatory), state (optional) and city (optional)

Please pay attention to request URL. You subaccount identificator ('port' value) is presented in url!

curl -X POST https://supernovanet.org/api/v1/subaccounts/YOUR_SUBACCOUNT_IDENTIFICATOR/generate-links \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey 00000000-0000-0000-0000-000000000000" \
  -d '{
    "link_type": 7,
    "mob": true,
    "res": true,
    "mix": true,
    "country": "US",
    "city": 123,
    "state": 45,
    "session": "rotate",
    "quantity": 1000
}'
Please find below description of each request fields:
{
  "link_type": 7, // Mandatory. This ID is from Proxy Link Formats
  "mob": true, // Mandatory. If you need Mobile proxies. Please pay attention that one of mob, res or mix fields must be true!
  "res": true, // Mandatory. If you need Residential proxies. Please pay attention that one of mob, res or mix fields must be true!
  "mix": true, // Mandatory. If you need Mixed proxies. Please pay attention that one of mob, res or mix fields must be true!
  "country": "US", // Mandatory! Country from list of available ones
  "city": 123,  // Optional: city id from Available States/Regions and Countries. Ignored if no that City available.
  "state": 45, // Optional: city id from Available States/Regions and Countries. Ignored if no that State available.
  "session": "rotate", // Mandatory. Possible values: "rotate", "keep"
  "quantity": 1000 // Optional. Links quantity. By default is one. Up to 10000, but specify reasonable amount. 
}'

Successful response on request will be:

{
  "data": [
    "http://YOUR_SUBACCOUNT_IDENTIFICATOR-iso-us-t-mrv-st-r-s-1cdvecqqnu:[email protected]:9090",
    "http://YOUR_SUBACCOUNT_IDENTIFICATOR-iso-us-t-mrv-st-r-s-xboz8dc60t:[email protected]:9090"
  ],
  "success": true
}