PersonaHub Automation API

The PersonaHub automation API lets you create and manage profiles, configure proxies and fingerprints, manage saved website credentials, and launch or close profile browsers.

Reading pages, clicking, typing, and taking screenshots require CDP or a compatible automation tool after the browser starts.

1. Before you start

1. Open the PersonaHub desktop app and sign in.
2. Enable the API in the app's automation settings, copy the API key, and check the port.
3. Make sure the browser engine is ready before launching a profile.
4. Keep the app running, signed in, and connected to the internet while using the API.

The API can only access the signed-in account's profiles. Profile creation is subject to the account's quota.

For remote access, replace 127.0.0.1 with the address of the computer running PersonaHub. Browsers, debugging ports, and returned file paths belong to that computer.

2. Conventions

2.1 Authentication

Every request except GET /health requires:

Authorization: Bearer <API_KEY>

For requests with a body, also send:

Content-Type: application/json

The API key does not replace account sign-in or grant additional account permissions.

2.2 Requests and responses

• Request bodies must be JSON objects, not arrays, strings, or null.
• Request bodies are limited to 256 KiB. An oversized request may have its connection closed directly.
• All successful endpoints listed here return 200, including creation and deletion.
• Responses use JSON and include Cache-Control: no-store.
• Profile and credential path IDs are UUIDs. Invalid path IDs return 404.
• Replace :id, :passwordId, :otpId, and :passkeyId with actual IDs.
• List endpoints do not support pagination parameters.
• PATCH preserves omitted fields; nested-field rules are described below. Do not use null in place of an omitted field.

Error response:

{
  "error": "Error description",
  "code": "not_found"
}

Handle errors using the HTTP status and code, not the wording or language of error.

3. Quick start

These commands use Bash/zsh syntax. Replace the API key and the UUID of an existing profile before running them.

export PERSONA_API_BASE='http://127.0.0.1:43110'
export PERSONA_API_KEY='<API_KEY>'

curl -sS "$PERSONA_API_BASE/health"

curl -sS "$PERSONA_API_BASE/v1/engine" \
  -H "Authorization: Bearer $PERSONA_API_KEY"

curl -sS "$PERSONA_API_BASE/v1/profiles" \
  -H "Authorization: Bearer $PERSONA_API_KEY"

export PROFILE_ID='<PROFILE_UUID>'

curl -sS -X POST "$PERSONA_API_BASE/v1/profiles/$PROFILE_ID/launch" \
  -H "Authorization: Bearer $PERSONA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"startupUrl":"https://example.com","extraArgs":["--remote-debugging-port=9222"]}'

A successful launch returns:

{"ok": true}

This confirms browser startup, not that a page, website login, or CDP endpoint is ready. Once the debugging port is available, query it with:

curl -sS http://127.0.0.1:9222/json/version

Connect using the returned webSocketDebuggerUrl, or the CDP HTTP address if your automation tool supports it. Port 43110 is the automation API port; 9222 is the example browser debugging port. Assign different debugging ports when enabling CDP for multiple profiles at once.

Close the browser started through the API:

curl -sS -X POST "$PERSONA_API_BASE/v1/profiles/$PROFILE_ID/close" \
  -H "Authorization: Bearer $PERSONA_API_KEY"

4. Service status and account entitlements

A successful /health response does not confirm account sign-in or engine readiness. The version returned by /v1/engine is the browser engine version, not the app version, and is an empty string when unavailable. ready does not indicate that a profile has launched or that CDP is available.

The entitlements object contains:

5. Profiles

5.1 Create and update fields

Minimal creation body:

{"name": "Automation profile"}

Omitted settings use defaults on creation. Updates to proxy and fingerprint change only the supplied subfields. Proxy detection may affect the timezone, as described in section 5.4.

Example partial update:

PATCH /v1/profiles/:id

{
  "name": "Automation profile A",
  "startupUrl": "https://example.com",
  "extraArgs": "--remote-debugging-port=9222"
}

Here, extraArgs is a string, unlike the string array used by the launch endpoints. Saved arguments do not support shell-style quoting; pass an argument containing spaces as one item in the launch endpoint's extraArgs array. Set startupUrl or extraArgs to an empty string in an update to clear its saved value.

5.2 Proxy settings

Configure the proxy in the profile's proxy field.

{
  "name": "US profile",
  "proxy": {
    "protocol": "socks5",
    "host": "proxy.example.com",
    "port": 1080,
    "username": "<PROXY_USERNAME>",
    "password": "<PROXY_PASSWORD>"
  }
}

Leaving the profile-specific proxy unset does not force a direct connection. App proxy-chain or system proxy settings may still affect the connection.

5.3 Fingerprint settings

Each creation randomly selects 8/12/16/20/24/32 CPU threads and 16/32 GB of memory. The random preset uses performance tier 3 for 8 threads and 4 otherwise. Explicit fields override the corresponding preset values. Updates preserve omitted fields, and launches do not randomize them again.

cpuPerformance tiers: 0 = Unknown, 1 = Low, 2 = Mid, 3 = High, 4 = Ultra.

Supported webrtcIpPolicy values:

• disable_non_proxied_udp
• default_public_interface_only
• default_public_and_private_interfaces
• default

UDP-enabled modes may expose direct IP addresses instead of the node IP. Close and relaunch the browser after changes.

5.4 Proxy exit information

When a proxy is configured without exit information, the API detects it automatically. A failed check returns proxy_probe_failed.

If you already have detection results, provide proxyIpInfo:

• If the request does not explicitly provide a nonempty fingerprint.timezone and the detected or supplied exit information includes a timezone, that timezone is used.
• Automatic detection does not change acceptLanguages. Supply it explicitly to change the language list.

5.5 Profile responses

Each list entry contains id, name, startupUrl, extraArgs, createdAt, updatedAt, and optional lastLaunchedAt.

Detail, creation, and update responses also contain:

• proxy: proxy connection settings, including the authentication password.
• fingerprint: fingerprint settings.
• acceptProxyChain: whether the profile accepts the app's proxy chain.
• appearanceLabel, appearanceBackgroundColor, and appearanceForegroundColor: appearance settings.

6. Browser lifecycle

6.1 Launch options

launch and command accept the same body. Send {} if no temporary options are needed.

{
  "startupUrl": "https://example.com",
  "extraArgs": ["--remote-debugging-port=9222"]
}

Launch arguments include the profile's saved arguments, the app's global launch arguments, and this call's extraArgs, in that order. Clearing the profile's saved arguments does not clear the app's global arguments.

These options apply only to this call and do not change the profile's saved values. extraArgs cannot override the data directory or browser lifecycle arguments managed by PersonaHub.

A successful launch only confirms browser startup. Calling it again may close and restart that profile. Do not use it to poll browser status.

6.2 Launch command

The command response contains:

Pass the returned values directly to a process-spawning API on the computer running PersonaHub. Do not concatenate them into a shell command or override the data directory.

For --remote-debugging-pipe, use command and have the caller start the process with the debugging pipes connected. launch does not return debugging pipes.

6.3 Usage limits

• Keep the PersonaHub desktop app running while using the browser.
• close does not manage browsers launched from the app UI or processes started by the caller using command.
• If no API launch is available to close, the API returns 404 with code not_running. The first close request can still succeed after the browser has exited on its own, so do not use this endpoint to check whether it is running.
• A successful close means closure was requested, not that the browser has exited.
• Do not launch multiple instances of the same profile concurrently.

7. Saved website credentials

7.1 Website passwords

Save request:

{
  "origin": "https://example.com",
  "username": "user@example.com",
  "password": "<WEBSITE_PASSWORD>"
}

PATCH requires at least one of these fields. Omitted fields keep their current values; empty strings are not allowed. signon_realm is generated automatically and is not accepted as a request field.

Summaries contain id, origin, signon_realm, and username; single-credential responses also include password. Saving the same sign-on realm and username updates the existing entry. Saving returns no ID; query the list afterward to obtain it.

Changes are provided to the browser on a subsequent launch. Deletion does not change the website account or remove credentials already loaded by a running browser. Later browser sync may overwrite changes or recreate deleted entries.

7.2 TOTP codes

Save fields:

List and save responses include id, label, issuer, accountName, algorithm, digits, and period. They do not return the secret.

Within the same profile, the same normalized secret updates or restores the existing entry. A different secret creates a new entry. Omitted metadata and settings use defaults on each save; they do not preserve existing values.

Example code response:

{
  "id": "<OTP_UUID>",
  "code": "012345",
  "expiresAt": "2026-09-17T08:00:30.000Z"
}

code is a string; preserve leading zeroes. Codes use the clock on the computer running PersonaHub. expiresAt is a UTC ISO timestamp. The API does not submit the code. Saving or deleting an entry does not enable or disable two-step verification on the website.

7.3 Passkeys

Each entry contains id, rpId, userName, and userDisplayName. Private keys are not returned. The automation API has no endpoint for creating or importing passkeys.

Deletion affects subsequent launches. It does not unregister the credential on the website or remove copies already loaded by a running browser. See the passkey guide for plan requirements when using passkeys in the browser.

8. Common errors

Related guides

• Create a profile
• Launch a profile browser
• Enable CDP
• Website password management
• TOTP guide
• Passkey guide