API overview

Use the REST API to start and stop browsers, manage saved profiles, and configure proxies and extensions. A start request returns the WebSocket URL used by your automation framework. For a first working script, follow the quickstart. The endpoint pages in this tab document request fields and responses.

Base URL

Use the API base URL assigned to your account in the Surfsky dashboard. https://YOUR_API_HOST is a placeholder for that URL. Calling a host that does not serve your account returns 403 namespace_not_allowed. The shell examples use SURFSKY_API_BASE_URL and SURFSKY_API_TOKEN; set them as shown in credentials. In the API playground, enter your full API base URL in baseUrl.

Authentication

Send the API token with REST management requests:

curl "$SURFSKY_API_BASE_URL/profiles/active" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN"

Use Content-Type: application/json for JSON request bodies. Extension uploads use multipart form data. Keep tokens in server-side environment variables or your secret store. Live CDP, DevTools, ChromeDriver, and screencast URLs carry access through the session identifier; keep those URLs private too.

Response shape

Read the schema for the endpoint you are calling. The API has several success formats:

Operation	Payload location
Start a one-time or persistent browser	`internal_uuid`, `ws_url`, and `inspector` at the top level.
Create a persistent profile	The new UUID in `data.uuid`; HTTP `201`.
List persistent profiles	A JSON array at the top level.
List active sessions	An array in `data`.
Scrape one page	Page result in `data`. A batch returns an array in `data`.
Many management and lookup calls	A `success` flag and `data`, sometimes with `msg`.

For example, a start response looks like this:

{
  "internal_uuid": "a8fb62f90611456aa75422b01c385a62",
  "ws_url": "wss://YOUR_API_HOST/proxy/a8fb62f90611456aa75422b01c385a62",
  "inspector": {
    "list": "https://YOUR_API_HOST/proxy/a8fb62f90611456aa75422b01c385a62/inspector",
    "pages": [],
    "screencast": "wss://YOUR_API_HOST/screencast/a8fb62f90611456aa75422b01c385a62/devtools/page/PAGE_ID"
  },
  "success": true
}

The IDs and URLs above are illustrative. Use the values returned by your request. Errors commonly include success: false, msg, data, and code, but forwarded errors can differ. See errors.

Starting a browser

A one-time session starts without a saved profile. Its profile state is discarded when it stops. A persistent profile saves the storage types you enable and can be started again.

curl -X POST "$SURFSKY_API_BASE_URL/profiles/one_time" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

The empty body uses a proxy pool available to your account. Supply your own connection if no pool is available. profile_uuid identifies a saved profile. Use the returned internal_uuid for stop, scrape, and live browser connections. These values may be equal; do not assume a new or different internal ID on every start. See session lifecycle.

Start one-time session

POST /profiles/one_time starts and returns a running browser. Configure fingerprints, proxies, Human actions, and CAPTCHA solving for the work you need.

Stop session

POST /profiles/{internal_uuid}/stop releases a running browser. Put this call in cleanup code so it also runs after failed navigation or framework connection.

Active sessions

GET /profiles/active lists one-time and persistent browsers currently running. Use one_time to distinguish them. POST /profiles/stop stops all browsers on the account. Check its failed list; use individual stop calls when other workers share the account.

Persistent profiles

Task	Endpoint
Create	POST /profiles
List	GET /profiles
Read settings	GET /profiles/{profile_uuid}
Update	PATCH /profiles/{profile_uuid}
Start	POST /profiles/{profile_uuid}/start
Delete one	DELETE /profiles/{profile_uuid}
Delete several	DELETE /profiles

Create with a title and a fingerprint containing os. Stop a profile before editing or deleting it. Starting an already running profile can return the existing session.

Cookies

Use export cookies and import cookies on a stopped persistent profile. See the cookie guide for JSON and Netscape formats and login-state requirements.

Scraping

POST /profiles/{internal_uuid}/scrape returns rendered HTML, cookies, and an optional screenshot from a running browser. Read Scraping API for a full lifecycle example and batch behavior.

Proxy reference

Use the proxy guide to choose a tier, target a location, provide a VPN, block domains, or route domains through different connections. Location lookup starts with countries or geographic pools. Shared proxies have their own country list. GET /proxies/quota is a legacy alias for premium quota, not a combined quota for both tiers. Check shared quota separately. Premium and shared traffic statistics report time windows.

Fingerprint reference

Look up renderers, screens, and device models. Leave fields generated unless your workload needs a specific value; see fingerprints.

Extensions

Upload a ZIP and use the returned UUID when starting a browser. The extension guide covers packaging, loading, updating metadata, and deletion.

CAPTCHA solving

Enable anti_captcha on the start request, then use the CAPTCHA CDP commands. GET /captcha/balance reports configured solver balances.

Endpoints that are not generated

The endpoints below forward live browser protocol traffic or expose account information outside the generated reference.

CDP over WebSocket

wss://YOUR_API_HOST/proxy/{internal_uuid}
wss://YOUR_API_HOST/proxy/{internal_uuid}/{path}

Connect using the returned ws_url. See the framework guides for the exact connection and cleanup steps.

DevTools HTTP

GET https://YOUR_API_HOST/proxy/{internal_uuid}/inspector
GET https://YOUR_API_HOST/proxy/{internal_uuid}/{path}
PUT https://YOUR_API_HOST/proxy/{internal_uuid}/{path}

The proxy exposes discovery endpoints such as /json/list and /json/version. See debugging to open a page’s inspector.

ChromeDriver

GET|POST|PUT|DELETE https://YOUR_API_HOST/chromedriver/{internal_uuid}/{path}

Start with enable_chromedriver: true, then use this URL as Selenium’s remote server. See the Selenium quickstart.

Screencast

wss://YOUR_API_HOST/screencast/{internal_uuid}/devtools/page/{page_id}

Use inspector.screencast from the start response to receive live JPEG frames. See Screencast for a viewer example.

Account limits

Endpoint	Reports
`GET /users/plan`	Account plan and allowances.
`GET /users/browser-limits`	Running browsers and capacity; `available` is present for capped accounts.

See limits for response details and how each limit affects a job.

Rate limits

Profile responses report minute and hour request limits in X-Ratelimit-Limit, X-Ratelimit-Limit-Hour, X-Ratelimit-Remaining, and X-Ratelimit-Remaining-Hour. Exhausting either window returns 429 rate_limits_reached. Other 429 codes represent browser or quota limits. Use the error code to decide what to do next.

Using the API

Profiles

Proxies

Fingerprints

Extensions

CAPTCHA

Base URL

Authentication

Response shape

Starting a browser

Start one-time session

Stop session

Active sessions

Persistent profiles

Cookies

Scraping

Proxy reference

Fingerprint reference

Extensions

CAPTCHA solving

Endpoints that are not generated

CDP over WebSocket

DevTools HTTP

ChromeDriver

Screencast

Account limits

Rate limits

​Base URL

​Authentication

​Response shape

​Starting a browser

​Start one-time session

​Stop session

​Active sessions

​Persistent profiles

​Cookies

​Scraping

​Proxy reference

​Fingerprint reference

​Extensions

​CAPTCHA solving

​Endpoints that are not generated

​CDP over WebSocket

​DevTools HTTP

​ChromeDriver

​Screencast

​Account limits

​Rate limits

Base URL

Authentication

Response shape

Starting a browser

Start one-time session

Stop session

Active sessions

Persistent profiles

Cookies

Scraping

Proxy reference

Fingerprint reference

Extensions

CAPTCHA solving

Endpoints that are not generated

CDP over WebSocket

DevTools HTTP

ChromeDriver

Screencast

Account limits

Rate limits