Skip to main content

LOCAL API v1.5

Introduction​

Using the v1.5 API in Undetectable, you will be able to retrieve a list of profiles, create, start, update and close them. In addition, with information you get, you will be able to connect various automation tools, such as Puppeteer, Selenium, Playwright, etc. in Chromium profiles.

Chromedriver for working with Selenium you can download here.

The program must be running to work with the API.

By default, the local server runs on port 25325, if this port is busy, it will start on a different port. In the settings of the program you can see the port and change it to the right one.

To access a local server, use IP 127.0.0.1, localhost or a local IP within your network and the port from the settings + the path you want to execute, e.g. http://localhost:25325/status.

All responses to the API look like:

{
"code": `<status code>`,
"status": `<status>`,
"data": `<return object>`,
}

where <status code> и <status> reflect status:

<status code><status>Description
0"success"success
1"error"error, <return object> = {"error":"error description"}

<return object> – Various data sent by the API, such as a list of profiles.

Errors are of the form:

{
    "code":1,
    "status":"error",
    "data":
    {"error": "error description"},
}

Requests​

Get status​

  • Path: /status
  • Method: GET

Description: Returns the status of the local server, whether it is running or not

Returning Data
{
    "code":0,
    "status":"success",
    "data":{},
}

Get profiles list​

  • Path: /list
  • Method: GET

Description: Returns the list of profiles on the Chromium browser available in the program 

{
    "code": 0,
    "status": "success",
    "data" {
        "profile_id1": {
            "name": "Profile1" // Profile name in program
            "status": "Available", // profile status сan be: "Started","Locked", "Available"
            "debug_port": "xxxx", // browser debug port, used for automation (empty value if the profile is not running). Only in Chromium
            "websocket_link": "ws://127.0.0.1:xxxx/devtools/browser/xxxxxx", // Browser link, used for automation (empty value if the profile is not running). Only in Chromium
            "folder": "Name", // Profile folder name
            "tags": ["tag1", "tag2", "tag3"], // Profile Tags
            "cloud_id": "", // Cloud profile ID
        "creation_date": 123456789, // Creation date Unix Timestamp
        "modify_date": 123456789, // Modification date Unix Timestamp
        },
        "profile_id2": {
            …},
        …
    },
}

Create profile​

  • Path: /profile/create
  • Method: POST

Description: Create profile with chosen parameters. All parameters are optional. Browsers list: Chrome, Edge, FireFox, IE, Opera, Safari, Yandex. OS list: Windows, Windows 7, Windows 8, Windows 8.1, Windows 10, Android, iPhone, iPad, Linux, Mac. If selected OS or Browser not exist in your configs list - it will use config with random OS or Browser
Format: JSON

Request parameters:
{
    "name": "profile with random settings", // Profile name
    "os": "Windows", // Configuration with what OS need to use
    "browser": "Chrome",  // Configuration with what Browser type need to use
    "cpu": 8, // Number of cores, possible values: 32, 24, 20, 16, 12, 10, 8, 7, 6, 5, 4, 3, 2, 1, 0
    "memory": 8,  // Amount of memory, possible values: 8, 4, 2, 1, 0
    "tags": ["tag1", "tag2"],  // Set tags list for profile
    "geolocation": "12.44, 13.524",  // Set geolocation for profile, if not available - it will take default settings
    "resolution": "1024x768",  // Screen resolution, possible values: "800x600", "960x540", "1024x768", "1152x864", "1280x720", "1280x768", "1280x800", "1280x1024", "1366x768", "1408x792", "1440x900", "1400x1050", "1440x1080", "1536x864", "1600x900", "1600x1024", "1600x1200", "1680x1050", "1920x1080", "1920x1200", "2048x1152", "2560x1080", "2560x1440", "3440x1440", "3840x2160", "5120x1440"
    "proxy": "socks5://127.0.0.1:5555:login:pass", // Change proxy in profile (you can use http, https, socks5 proxy and proxy with login/pass or without login/pass)
    "notes": "Text", // Change notes in profile
    "folder": "testFolder", // Profile folder
    "language": "ru-RU, en-US", // It's possible to choose 2 languages
    "cookies":,   [{}] // Import cookies
    "type": "cloud", // Profile type: cloud, local
    "group": "group_example", // If not exist, will use group from default settings
    "configid": "id", // Config ID, if you enter it, then OS и Browser will be ignored
    "accounts": [  // Import accounts from different sites to a profile
        {"website": "facebook.com", "username": "test@gmail.com", "password": "123456"},
        {"website": "mail.com","username": "test@gmail.com","password": "123456"}
    ]
}
Returning Data:
{
    "code": 0,
    "status": "success",
    "data":  {
               "profile_id": "xxxxxxxx...", // Unique profile ID
               "name": "profile with random settings" // Profile name
               }

}

Start profile​

  • Path: /profile/start/<profileID>
  • Method: GET

Description: Starts a profile with the selected <profileID>. In link parameters you can add:

  • chrome_flags parameter and enter any flags you want, but need to encode them to URL encoding, as example: ?chrome_flags=--blink-settings%3DimagesEnabled%3Dfalse%20--disable-webgl2
  • start-pages parameter and set start pages, but need to encode them to URL encoding, as example: ?start-pages=https%3A%2F%2Fgoogle.com%2Chttps%3A%2F%2Fya.ru
Returning Data
{
  "code":0,
  "status":"success",
  "data":{
    "name": "Profile1" // Profile name in the program
    "websocket_link":"ws://127.0.0.1:xxxx/devtools/browser/xxxxxx",  // Browser link, used for automation (empty value if the profile is not running). Only in Chromium
    "debug_port": "xxxx", // browser debug port, used for automation (empty value if the profile is not running). Only in Chromium
    "folder": "Name", // Profile folder name
    "tags": ["tag1", "tag2", "tag3"] // Profile Tags
  },
}

Close profile​

  • Path: /profile/stop/<profileID>
  • Method: GET

Description: Stops the profile with the selected <profileID>

Returning Data:
{
  "code": 0,
  "status": "success",
  "data": {}
}

Update profile​

  • Path: /profile/update/<profileID>
  • Method: POST

Description: Update information in profile with the selected <profileID>. All parameters are optional
Format: JSON

Request parameters:
{
    "name": "Profile Name", // Profile name
    "proxy": "socks5://127.0.0.1:5555:login:pass", // Change proxy in profile (you can use http, https, socks5 proxy and proxy with login/pass or without login/pass)
    "notes": "Text", // Change notes in profile
    "folder": "testFolder", // Profile folder
    "tags": ["tag1", "tag2"],  // Set tags list for profile, it will delete old tags, with [] you can delete all tags from profile
    "geolocation": "12.44, 13.524",  // Set geolocation for profile, you can set empty string "" to set default geo from software settings
    "cookies":   [{}], // Import cookies
    "type": "cloud", // Profile type: cloud, local
    "group": "group_example", // If not exist, will use group from default settings
    "accounts": [  // Import accounts from different sites to a profile
        {"website": "facebook.com", "username": "test@gmail.com", "password": "123456"},
        {"website": "mail.com","username": "test@gmail.com","password": "123456"}
    ]
}
Returning Data:
{
  "code": 0,
  "status": "success",
  "data": {}
}

Delete profile​

  • Path: /profile/delete/<profileID>
  • Method: GET

Description: Delete the profile with the selected <profileID>

Returning Data:
{
  "code": 0,
  "status": "success",
  "data": {}
}

Clear profile data​

  • Path: /profile/cleardata/<profileID>
  • Method: GET

Description: Clear all data (cookies, history, bookmarks, cache and etc.) from profile with selected <profileID>

Returning Data:
{
    "code": 0,
    "status": "success",
    "data": {}
}

Get cookies​

  • Path: /profile/cookies/<profileID>
  • Method: GET

Description: Export cookies from profile with selected <profileID>

Returning Data:
{
    "code": 0,
    "status": "success",
    "data": {}
}

Send profiles to cloud​

  • Path: /profile/tocloud
  • Method: POST

Description: Send profiles to cloud
Format: JSON

Request parameters:
{
    "profiles":["9b24cd2604d1b8260123242ab1f30c", "f4cbe3c89618bfc9647ba8a47c13f6"]
}
Returning Data:
{
    "code": 0,
    "status": "success",
    "data":  {}
}

Switch profiles to local​

  • Path: /profile/tolocal
  • Method: POST

Description: Makes profiles local
Format: JSON

Request parameters:
{
    "profiles":["9b24cd2604d1b8260123242ab1f30c", "f4cbe3c89618bfc9647ba8a47c13f6"]
}
Returning Data:
{
    "code": 0,
    "status": "success",
    "data":  {}

}

Update browser version​

  • Path: /profile/updatebrowser/<profileID>
  • Method: GET

Description: Update browser version in profile with <profileID>
Format: JSON

Returning Data:
{
    "code":0,
    "status": "success",
    "data": {},
}

Get configurations list​

  • Path: /configslist
  • Method: GET

Description: Returning active configurations list
Format: JSON

Returning Data:
{
    "code":0,
    "status":"success",
    "data":     {
        "config_id1": 
        {
            "os": "Windows 10" // OS
            "browser":"Chrome 115", // Browser type and version
            "useragent": "xxxx", // UserAgent in configuration
            "webgl": "Apple GPU", // WebGL in configuration
            "screen": "1024x768", // Screen resolution
        },
        "config_id2": 
        {
         …
        }, 
        …
    },

}

Get groups​

  • Path: /groupslist
  • Method: GET

Description: Returning groups list
Format: JSON

Returning Data:
{
    "code":0,
    "status": "success",
    "data": {["group1", "group2"]},
}

Get full info of profile​

  • Path: /profile/getinfo/<profileID>
  • Method: GET

Description: Requests profile information with the selected <profileID>
Format: JSON

Returning Data:
{
    "code":0,
    "status": "success",
    "data": {
            "name": "Profile1" // Profile name in software
            "status": "Available", // profile status, can be: "Started","Locked", "Available"
            "debug_port": "xxxx", // browser debug port, used for automation (empty value if the profile is not running). Only in Chromium
            "websocket_link": "ws://127.0.0.1:xxxx/devtools/browser/xxxxxx", // Browser link, used for automation (empty value if the profile is not running). Only in Chromium
            "configid": "id" // Config ID
            "cloud_id": ""
            "type": "cloud" // Profile type: cloud, local
            "proxy": "socks5://127.0.0.1:5555:login:pass", // Proxy
            "folder": "Name", // Folder name
            "tags": ["tag1", "tag2", "tag3"], // Tags list
            "notes": "Text", // Profile notes
            "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 Edg/114.0.1823.43", // useragent 
            "browser": "Edge 114.0.1823.43", // Browser in profile
            "os": "Windows 10", // OS in profile
            "screen": "1366x768", // Screen resolution
            "language": "en-US,en;q=0.9,ak-GH;q=0.8,ak;q=0.7", // profile language
            "cpu": 8, //  CPU
            "memory": 4, // Amount of memory
            "creation_date": 123456789, // Creation date Unix Timestamp
            "modify_date": 123456789, // Modification date Unix Timestamp
    },
}

Examples​

Puppeteer (Node.js)​

Node.js Puppeteer Running a profile with a specific name and opening an undetectable.io page in that profile:

const puppeteer = require('puppeteer');
const axios = require('axios');

const port = 25325; // Port
const ip = '127.0.0.1'; // Local IP
const profileName = ‘TestProfile’; // Name profile

const sleep = (ms) => {
    return new Promise((resolve) => setTimeout(resolve, ms));
};

axios.get('http://' + ip + ':' + port + '/status').then(response => {
    if (response.data.code == 0) {
        axios.get('http://' + ip + ':' + port + '/list').then(async response => {

            for (var profile in response.data.data) {
                // Starting a specific profile and navigating to the page
                if (response.data.data[profile].name == profileName ) {
                axios.get('http://' + ip + ':' + port + '/profile/start/' + profile).then(async response => {
                try {
                const browser = await puppeteer.connect({
                browserWSEndpoint: response.data.data.websocket_link,
                defaultViewport: null
                });
                const page = await browser.newPage();
                await sleep(1000);
                await page.goto('https://undetectable.io');
                } catch (e) {
                console.log(e);
                }
                })
                .catch(error => {
                console.log(error);
                });
                }
            }
        })
        .catch(error => {
            console.log(error);
        });
    }
})
.catch(error => {
    console.log(error);
});

Selenium (Python)​

Python + Selenium Running profiles with a specific folder and opening few sites in these profiles:

from time import sleep
import requests
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service

address = "127.0.0.1" # Local API IP address (if you work from another PC on the same network or a port is open in the router settings, you can access the local API remotely and this address will need to be changed)
port_from_settings_browser = '25325' # Local API port (can be found in the program settings)
chrome_driver_path = "chromedriver.exe" # Path to chromedriver for v110
ser = Service(chrome_driver_path) 
chrome_options = Options()
list_response = requests.get(f'http://{address}:{port_from_settings_browser}/list').json()['data'] # Send a request to the local API to get a list of profiles
profile_id = ''

for key, value in list_response.items(): # Loop through the list of profiles and run them one by one
        if value['folder'] == 'test': # Here you can add a check to run only the profiles you need (in this example, we run the profiles that are in the 'test' folder)
            profile_id = key
            if value['status'] == 'Available': # If the profile is not running, then run the profile and take the debug_port
                start_profile_response = requests.get(f'http://{address}:{port_from_settings_browser}/profile/start/{profile_id}', timeout=5).json()['data']
                debug_port = start_profile_response['debug_port']
            if value['status'] == 'Started': # If the profile is running, then we simply take the debug_port from the available data
                debug_port = value['debug_port']
            if value['status'] == 'Locked': # If the profile is Locked, then skip
                continue
            if debug_port: # We check if the browser has a connection port (WebEngine profiles doesnt have ports, so we close them immediately)
                chrome_options.debugger_address = f'{address}:{debug_port}'
                driver = webdriver.Chrome(service=ser, options=chrome_options)
                driver.get("https://whoer.net/") # Open whoer.net in active tab
                driver.switch_to.new_window('tab') # Create a new tab and switch to it
                driver.get(url='https://browserleaks.com/js') # Open browserleaks.com/js in active tab
                # You can add any other actions here      
            sleep(5) # Wait 5 sec
            requests.get(f'http://{address}:{port_from_settings_browser}/profile/stop/{profile_id}') # Stop profile