JustBrowser REST API Postman Guide: Profiles, Sessions, Proxies

Most of the trouble with the JustBrowser REST API comes from mixing up its concepts. Profile creation and session launching are separate steps. A saved proxy isn't a tested proxy.

Postman helps with this. Not because it's magic, but because it makes you slow down and see exactly what each endpoint does before you wrap it in Python. If you're evaluating JustBrowser, building automation, or just trying to understand how multi-account browser APIs work — start here. By the end of this walkthrough, you'll have a working Postman collection and a clear map of the JustBrowser REST API surface.

Prerequisites

Before we start:

• Postman — download here
• JustBrowser Pro ($9.99/mo or $99.99/year) — includes REST API access, and so does the 7-day trial. Team seats cannot use the API, so you'll need your own subscription or trial to follow along.
• Your API token — find it on the AI page in the app. The API is local only, bound to 127.0.0.1 (port configurable), so JustBrowser must be running
• Basic REST familiarity — you know what GET vs POST means

No coding required. That's the point. We're exploring the API without touching an IDE.

Step 1: Set Up Postman Environment

First, create an environment to store your credentials so you're not copying your API key into every request.

Open Postman. Click Environments (left sidebar) → Create Environment. Name it "JustBrowser API" and add these variables:

Click Save. Select this environment from the dropdown in the top-right corner.

Why bother? You'll make a lot of requests while exploring. Hardcoding the API key into each one is tedious and error-prone. Plus, when you rotate your key (and you should), you update one variable instead of hunting through a collection.

Step 2: Create Your First Profile

Profiles are the core object. Each profile stores a complete browser identity — its own cookies, storage, proxy and identity parameters. Creating a profile doesn't launch anything. It just saves the configuration.

Create a new request in Postman:

• Method: POST
• URL: {{base_url}}/profiles
• Headers: Add Authorization: Bearer {{api_key}} and Content-Type: application/json
• Body (raw JSON):

{
  "name": "Test Profile via Postman",
  "os": "windows",
  "browser": "chrome",
  "locale": "en-US"
}

Hit Send. You should get back a 201 with the new profile inside the data envelope every answer uses, shaped like this (check the docs for the full object):

{
  "data": {
    "id": "<profile id>",
    "name": "Test Profile via Postman",
    ...
  }
}

That id is what you'll use for everything else — launching sessions, updating settings, deleting the profile. Save it as a Postman variable right away: highlight the id in the response body and choose Set as variable → profile_id.

Create accepts a short list of fields: name, folder_id, notes, os, browser, locale and device_type. There's no fingerprint object in the request. JustBrowser generates the identity parameters itself, so you pick the OS and browser and let the app fill in the rest. The API docs list every field; check them before adding anything to the body.

Step 3: List All Profiles

Quick sanity check: make sure the profile actually exists.

• Method: GET
• URL: {{base_url}}/profiles
• Headers: Authorization: Bearer {{api_key}}

Send it. You'll get your profiles back, including the one you just created.

The new profile appears in the list. Nothing has been launched yet; that changes in the next step.

If you manage a lot of profiles, check the docs for the list endpoint's search, filter and sort parameters before pulling everything at once. A huge JSON blob is miserable to scroll in Postman's console. For the people-side of running many accounts, see managing client ad accounts as an agency.

Step 4: Launch a Session

Here's where it gets interesting. Launching a session spins up an actual Chromium instance using your profile's configuration and returns a WebSocket endpoint.

• Method: POST
• URL: {{base_url}}/profiles/{{profile_id}}/start
• Headers: Authorization: Bearer {{api_key}}, Content-Type: application/json
• Body:

{
  "headless": false
}

The start call runs headless unless the body says {"headless": false}, so send it whenever you want a visible window. The response includes a cdp_url:

{
  "data": {
    "cdp_url": "ws://127.0.0.1:PORT/devtools/browser/<guid>",
    ...
  }
}

That cdp_url is the Chrome DevTools Protocol connection. Playwright, Puppeteer, and Selenium all use this to control the browser. Driving a browser by typing raw CDP messages into Postman isn't practical, so use Postman to verify the launch worked and grab the endpoint for your automation code.

Timeouts here? Check that JustBrowser is running locally. The API is just the orchestration layer; the actual browser launches on your own Windows or macOS machine. Launch a lot of profiles at once and your laptop will let you know about it.

Step 5: Configure a Proxy

Plenty of multi-account setups use proxies. Each profile can have its own proxy (HTTP, HTTPS or SOCKS5), either one you bring or one you buy in the app. In the API a proxy is its own object, so you create it separately from the profile:

• Method: POST
• URL: {{base_url}}/proxies
• Headers: Authorization: Bearer {{api_key}}, Content-Type: application/json
• Body:

{
  "protocol": "socks5",
  "host": "proxy.example.com",
  "port": 1080,
  "username": "your-user",
  "password": "your-pass"
}

Save the returned proxy id as a Postman variable. Attaching it to a profile is a separate call; the exact route and field are in the API docs under the proxy and profile groups, so copy it from there rather than from this post.

Don't assume a saved proxy is a working proxy. Fat-finger the port or the credentials and you may not find out until you start a session. It's an easy mistake to make.

Quick test: after attaching the proxy, start the profile and open an IP-check page in it. Compare the address it shows to your expected proxy IP. Match? You're good. Mismatch? Check your proxy credentials.

If your provider uses a gateway pattern where the same host:port rotates IPs, rotation is configured with the provider, not in JustBrowser.

Step 6: Stop a Session

Sessions consume resources. Don't leave them running. Seriously.

• Method: POST
• URL: {{base_url}}/profiles/{{profile_id}}/stop
• Headers: Authorization: Bearer {{api_key}}

This ends the session. Note that browser.close() from Playwright only disconnects; the profile keeps running until you call stop. You can launch the same profile again anytime — the profile persists, only the session ends.

If your automation crashes without stopping sessions, you'll accumulate orphaned browser processes. Not the API's fault, but something to handle in your code. Forgetting a try/finally leaves browser processes running with nobody watching them.

Step 7: Delete a Profile

For cleanup or when you're done testing:

• Method: DELETE
• URL: {{base_url}}/profiles/{{profile_id}}
• Headers: Authorization: Bearer {{api_key}}

Response: 200. The profile is gone, along with its browser data on this computer and its cloud copy. If the profile is still running, the delete is refused with a 409, so stop it first.

Permanent. No undo. If you have 50 profiles and accidentally delete the wrong one... well, that's why it helps to name production profiles with clear prefixes like prod_client_acme, and test profiles with test_ or tmp_.

Common Errors and Fixes

401 Unauthorized

Cause: Missing or invalid API key.

Fix: Check that your Authorization header is Bearer <key> (with a space after Bearer). Verify the token comes from the AI page of an account with a subscription or trial — team seats have no API access. If you recently rotated your key, update Postman's environment variable.

Profile not found

Cause: The profile ID doesn't exist or was deleted (you'll get a 404-style error).

Fix: List all profiles (GET /profiles) to confirm the ID. Copy-paste errors are common. If you're using Postman variables, make sure {{profile_id}} is set.

Starting a profile that is already running

Cause: You tried to launch a profile that already has an active session. The exact status code and error code are in the docs; branch on error.code, never the message.

Fix: Stop the existing session first (POST /profiles/{id}/stop), then launch again. Think of it as one session per profile at a time, which stops two scripts fighting over the same browser.

Validation errors

Cause: A field the API doesn't accept, or a malformed body. A VALIDATION_ERROR carries details as an array of issues.

Fix: Read the issues, compare your body against the create fields listed in Step 2, and check the JSON is well-formed. If requests fail with no clear reason, restart JustBrowser and try again.

Building Your JustBrowser REST API Collection

By now you've got a handful of loose requests. Organize them into a collection:

1. Create new collection: "JustBrowser API"
2. Drag your requests into folders: "Profiles", "Sessions", "System"
3. For each request, save example responses (three dots → Save Response → Save as Example)
4. Export the collection (three dots on collection → Export) as a JSON file

That export is your documentation. Share it with teammates. Import it on a new machine. The example responses help onboard people who've never seen the API.

You can also generate code from any request — click the code icon (</>) on the right side, pick your language (Python, JavaScript, cURL, whatever), and Postman spits out working code. Not perfect code, honestly. The generated Python is a starting point. That's a common place to begin when moving from Postman exploration to actual automation scripts.

For folks building with Playwright or Puppeteer, the Playwright and Puppeteer guide covers the CDP connection side that Postman can't do. Same API, different tooling.

Frequently Asked Questions

Do I need coding skills to use the JustBrowser API?

No. Postman gives you a point-and-click interface for making API calls. You can create profiles, launch sessions, and configure proxies without writing a single line of code. That said, the real power comes when you graduate to Playwright or Puppeteer — but Postman is a great way to learn the API surface first.

What's the difference between creating a profile and launching a session?

Creating a profile stores the configuration — OS, browser, locale and the identity parameters JustBrowser generates. Launching a session actually starts a browser instance using that profile's settings and returns a WebSocket endpoint you can connect to. Think of it like the difference between saving a document and opening it.

Can I use Postman to connect to launched browser sessions?

Postman can launch sessions and get the CDP WebSocket URL back, but controlling the browser through that WebSocket is a job for a tool that speaks Chrome DevTools Protocol — like Playwright, Puppeteer, or even Chrome's own DevTools. Use Postman for the HTTP parts and a CDP library for the browser.

How do I test that my proxy settings work before running automation?

After creating a profile with proxy settings, start the profile and open an IP-check page in it. Compare the address to your expected proxy IP. If they match, your proxy is working. If not, check the proxy credentials and format.

Next Steps

You've got a working Postman collection and a mental map of the API. From here:

• Automate with Playwright — the Playwright and Puppeteer guide shows how to connect to launched sessions and run actual automation; for Python, see async Playwright with browser profiles
• Check the setup — once you're launching sessions, open an IP-check page in a started profile to confirm the proxy and timezone are what you set

The API surface we covered here — profiles, sessions, proxies — is only part of what's available. The API has 108 operations across 15 groups, including bulk profile creation (up to 100 per call from a naming pattern). The docs list them all. This core loop (create, configure, launch, stop) is where most automation starts.

Now stop reading and go build something.

---

Try JustBrowser

A multi-account browser for teams, built on a custom Chromium engine with native C++ integration (not extension-based), patched on every upstream release. 40+ identity parameters. REST API for Playwright, Puppeteer, Selenium. One plan: $9.99/month or $99.99/year. 7-day free trial, card required — cancel any time in the seven days and you are not charged. Unlimited profiles, unlimited cloud sync, unlimited team seats.

Get started → · How it compares with Multilogin, GoLogin and AdsPower