Api

Start one time profile browser

One time profile browser doesn't save it's state after stop, you have to provide proxy on every start.

One time profile request

POST /profiles/one_time

Parameters

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
proxy	false	Body	str	Description
open_vpn	false	Body	object	Description
cookies	false	Body	list of objects	Description
fingerprint	false	Body	object	Description
browser_settings	false	Body	object	Description

Proxy

About proxy and open vpn

Either proxy or open vpn might be provided but not both

Proxy as an url string, allowed schemes are ['http', 'https', 'socks5', 'ssh'] with or without auth that will be used by browser

info

Required: false

Position: body

Key:

proxy

Examples:

http proxy with auth

http://username:[email protected]:5555

http proxy without auth

http://1.1.1.1:5555

socks5 proxy with auth

socks5://username:[email protected]:5555

socks5 proxy without auth

socks5://1.1.1.1:5555

ssh proxy with auth

ssh://username:[email protected]:22

ssh proxy without auth

ssh://1.1.1.1:22

Request example:

curl -X 'POST' \
  '<API_URL>/profiles/one_time' \
  -H 'accept: application/json' \
  -H 'x-cloud-api-token: <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "proxy": "http://1.1.1.1:5555"
}'

OpenVPN

About proxy and open vpn

Either proxy or open vpn might be provided but not both

Object with openvpn config

info

Required: false

Position: body

Key:

open_vpn

Field	Required	Type	Description
config	true	string	Content of .ovpn file
username	true	string	Username will be used to connect to openvpn server
password	true	string	Password will be used to connect to openvpn server

Request example:

curl -X 'POST' \
  '<API_URL>/profiles/one_time' \
  -H 'accept: application/json' \
  -H 'x-cloud-api-token: <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "open_vpn": {"config": "config", "username": "username", "password": "password"}
}'

Cookies

Cookies that will be loaded in browser on start

info

Required: false

Position: body

Key:

cookies

Default:

null

JSON Cookies

[
    {
        "domain": ".google.com",
        "expirationDate": 1639134293.313654,
        "hostOnly": false,
        "httpOnly": false,
        "name": "1P_JAR",
        "path": "/",
        "sameSite": "no_restriction",
        "secure": true,
        "value": "2021-11-10-11"
    }
]

Mozilla Cookies

[
    {
        "Path raw":"/",
        "Samesite raw":"no_restriction",
        "Name raw":"NID",
        "Content raw":"2021-11-10-11",
        "Expires raw":"1639134293",
        "Host raw":"https://.google.com/",
        "This domain only raw":"false",
        "HTTP only raw":"false",
        "Send for raw":"true"
    }
]

Nescape Cookies:

some.host\tTRUE\t/\tTRUE\t123\tname\tvalue
some2.host\tTRUE\t/\tTRUE\t111\tname2\tvalue2

Fingerprint

Customize fingerprint that will be used in browser

info

Required: false

Position: body

Key:

fingerprint

Default:

{
  "os": "win"
}

Field	Type	Description
os	String enum: [win, mac]	Operation system will be used to generate profile data

Win Profile

{
  "os": "win"
}

Mac Profile

{
  "os": "mac"
}

Browser settings

Customize some browser settings

info

Required: false

Position: body

Key:

browser_settings

Default:

{
  "inactive_kill_timeout": 30
}

Field	Type	Description
inactive_kill_timeout	Positive Integer	In case no requests to browser will be made during this period browser will be shut down

Example

Python async
Python sync
Node.js
Curl

import asyncio

import httpx

async def main():
    headers = {"X-Cloud-Api-Token": "<API_TOKEN>"}
    body = {"proxy": "<proxy>", "browser_settings": {"inactive_kill_timeout": 30}}

    async with httpx.AsyncClient(base_url="https://api-public.surfsky.io") as client:
        response = await client.post("/profiles/one_time", json=body, headers=headers, timeout=30)

    print(response.json())

if __name__ == "__main__":
    asyncio.run(main())

import httpx

def main():
    headers = {"X-Cloud-Api-Token": "<API_TOKEN>"}
    body = {"proxy": "<proxy>", "browser_settings": {"inactive_kill_timeout": 30}}

    with httpx.Client(base_url="https://api-public.surfsky.io") as client:
        response = client.post("/profiles/one_time", json=body, headers=headers, timeout=30)

    print(response.json())

if __name__ == "__main__":
    main()

const https = require('https');

const urlparams = {
    host: 'https://api-public.surfsky.io',
    port: 443,
    path: '/profiles/one_time',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Cloud-Api-Token': '<API_TOKEN>'
    }
};

function onResponse(response) {
    var data = '';

    response.on('data', function(chunk) {
        data += chunk;
    });
    response.on('end', function() {
        console.log(JSON.parse(data));
    });
}

const request = https.request(urlparams, onResponse);

request.write(JSON.stringify({
    'proxy': '<proxy>',
    'browser_settings': {'inactive_kill_timeout': 30}
}));
request.end();

curl -X 'POST' \
'https://api-public.surfsky.io/profiles/one_time' \
-H 'accept: application/json' \
-H 'x-cloud-api-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"proxy": "<proxy>",
"browser_settings": {
  "inactive_kill_timeout": 30
}
}'

Response: 200

{
  "browser_uuid": "{browser_uuid}",
  "ws_url": "wss://<API_URL>/proxy/{browser_uuid}",
  "inspector": {
    "list": "https://<API_URL>/proxy/{browser_uuid}/inspector",
    "pages": [{
      "page_title": "New Tab",
      "page_url": "chrome://newtab/",
      "devtools_url": "https://<API_URL>/proxy/{browser_uuid}/inspector/devtools/..."
    }]
  },
  "success": true
}

Response: 400

{
  "error": "Internal error",
  "success": false
}

{
  "error": "Bad proxy",
  "success": false
}

Response 429

Body

{
  "error": "Your access to the API has been temporarily suspended. Please check the API documentation and handle 429 errors on your side",
  "sucess": false
}

Headers

{
  "Retry-After": 0,                       # if 0 - feel free to send next request
  "X-Ratelimit-Limit": 200,               # RPM (requests per minute) limit
  "X-Ratelimit-Limit-Hour": 3000,         # RPH (requests per hour) limit
  "X-Ratelimit-Remaining": 4,             # remaining RPM
  "X-Ratelimit-Remaining-Hour": 2999,     # remaining RPH
  "X-Ratelimit-Reset": 1671789217         # unix timestamp
}

Browser ws url

Endpoint that proxy ws connection to browser, mostly used by third party apps like playwright or puppeteer.

Request

WS /proxy/{browser_uuid}

Parameters

Name	Place	Type	Description
`browser_uuid`	Path	str	Browser uuid returned by `/profiles/one_time` endpoint

Response: 404

{
  "error": "Profile not found"
}

Persistent profiles

Persistent profiles are not deleted after stop, you can create/modify/delete them, export/import cookies.

Create

Create new persistent profile

POST /profiles

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
title	true	Body	str	Profile title
fingerprint	true	Body	object	Description
proxy	false	Body	str	Proxy as an url string
cookies	false	Body	str or list of objects	Json, Mozilla or netspace cookies

Fingerprint

Fingerprint will be used to create new persistent profile

info

Required: true

Position: body

Key:

fingerprint

Default:

{
  "os": "win"
}

Field	Type	Description
os	String enum: [win, mac]	Operation system will be used to generate profile data

Win Profile

{
  "os": "win"
}

Mac Profile

{
  "os": "mac"
}

Get

Get profile info

GET /profiles/{uuid}

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
uuid	true	Path	str	Profile uuid

Update

Update persistent profile

About unchangable fields

Note that you can't update profile's os, os_arch and os_version fields

PATCH /profiles/{uuid}

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
uuid	true	Path	str	Profile uuid

Delete

Delete persistent profile

DELETE /profiles/{uuid}

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
uuid	true	Path	str	Profile uuid

Delete batch

Delete persistent profile

DELETE /profiles

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
uuids	true	Body	list of str	List of uuids of profiles

List

Get persistent profiles

GET /profiles

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
page	false (default: 0)	Query	int	Page number
page_len	false (default: 100)	Query	int	Number of profiles per page
ordering	false (default: active)	Query	Enum{'created', '-created', 'active', '-active', 'title', '-title'}	How to order profiles, "-" prefix means reverse order

Start

Start persistent profile

POST /profiles/{uuid}/start

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
uuid	true	Path	str	Profile uuid
proxy	false	Body	str	Proxy as an url string, allowed schemes are ['http', 'https', 'socks5', 'ssh'] with or without auth that will be used by persistent browser instead of proxy saved in profile
open_vpn	false	Body	object {config: str(required), username: str, password: str}	Open config object that will be used by persistent browser instead of proxy saved in profile

About proxy and open vpn

Either proxy or open vpn has to be provided in case profile doesn't have proxy

Stop

Stop persistent profile

POST /profiles/{uuid}/stop

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
uuid	true	Path	str	Profile uuid

Active

Get running profiles

GET /profiles/active

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token

Export cookies

Export profile cookies

GET /profiles/{uuid}/cookies?export_format={export_format}

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
uuid	true	Path	str	Profile uuid
export_format	false (default: json)	Path	Enum{json, netscape}	json or netscape format to export

Import cookies

Import cookies to profile

POST /profiles/{uuid}/cookies

Name	Required	Place	Type	Description
`X-Cloud-Api-Token`	true	Header	str	Provided api token
uuid	true	Path	str	Profile uuid
cookies	true	Body	object	Cookies to import in json, netscape or mozilla format

Api

Start one time profile browser​

One time profile request​

Parameters​

Proxy​

OpenVPN​

Cookies​

JSON Cookies​

Mozilla Cookies​

Nescape Cookies:​

Fingerprint​

Win Profile​

Mac Profile​

Browser settings​

Example​

Response: 200​

Response: 400​

Response 429​

Body​

Headers​

Browser ws url​

Request​

Parameters​

Response: 404​

Persistent profiles​

Create​

Fingerprint ​

Win Profile​

Mac Profile​

Get​

Update​

Delete​

Delete batch​

List​

Start​

Stop​

Active​

Export cookies​

Import cookies​

Start one time profile browser

One time profile request

Parameters

Proxy

OpenVPN

Cookies

JSON Cookies

Mozilla Cookies

Nescape Cookies:

Fingerprint

Win Profile

Mac Profile

Browser settings

Example

Response: 200

Response: 400

Response 429

Body

Headers

Browser ws url

Request

Parameters

Response: 404

Persistent profiles

Create

Fingerprint

Win Profile

Mac Profile

Get

Update

Delete

Delete batch

List

Start

Stop

Active

Export cookies

Import cookies