OvoBrowser Local API Usage Tutorial

The ovoBrowser local API is used to manage the browser environment, groups, tags, proxies, recycle bin, and browser processes locally. Interface only listens127.0.0.1No Token, Bearer Token orx-api-key.

1. Startup method

Desktop automatic startup

After successful account login, the local API will automatically start and save the current port. The next saved session will automatically start after successful recovery. Default address:

http://127.0.0.1:50325

The actual port is based on the client's "API&MCP" page. Google、GitHub、 Both account password login and invitation registration will ultimately establish the same login session, so after successfully entering the account, the local API will be launched.

If the service is manually stopped in the client, the current port will be immediately closed; It will still automatically start the next time the login or session is successfully restored.

CLI mode

First successfully log in on the desktop client and remain logged in, then execute:

& "C:\Program Files\ovoBrowser\ovoBrowser.exe" --cli --api-port 50325

Use the actual installation path for the program.--api-portOptional. If omitted, the saved port will be used. The CLI reuses the account session in the operating system's secure storage and does not accept account passwords or Tokens from the command line.

“Remain logged in” means that you have not clicked Log Out in the desktop client and that the saved session is still valid. If you have logged out, the session has expired, or the application data has been cleared, you need to reopen the desktop client and log in again. Google/GitHub login must also be completed in the desktop client.

2. Calling Rules

• All APIs usePOST, with parameters placed in the JSON Body.

• Use the request headerContent-Type: application/json.

• Environment identification is recommended usingid; most APIs also supportseqas the environment sequence number.

• Pagination parameterpagefrom0At the beginning,pageSizeThe scope is1-100.

• Accounts, cookies, 2FA keys, and proxy passwords are sensitive information and should not be written into public logs.

Successful response:

{"success":true,"data":{}}

Failed response:

{"success":false,"msg":"失败原因"}

3. Overview of interfaces

4. Health check ups

curl --location 'http://127.0.0.1:50325/health' \
  --header 'Content-Type: application/json' \
  --data '{}'

Returndata.running=trueIndicates that the port has been started. By calling the environment list again, it can be confirmed that the account session and workspace have been restored.

5. Grouping API

Grouping is used for single choice classification: an environment can belong to at most one group, throughgroupIdBinding.

Group List

curl --location 'http://127.0.0.1:50325/group/list' \
  --header 'Content-Type: application/json' \
  --data '{}'

data.listIt is a grouped array,_count.profilesIt is the number of environments in the group.

Add Group

curl --location 'http://127.0.0.1:50325/group/create' \
  --header 'Content-Type: application/json' \
  --data '{"name":"电商账号","color":"#3478F6"}'

Edit Group

idandgroupIdYou can locate groups. Only transmit the fields that need to be changed, except for the positioning field.

curl --location 'http://127.0.0.1:50325/group/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"分组ID","name":"重要电商账号","color":"#16A34A"}'

Delete Group

curl --location 'http://127.0.0.1:50325/group/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"分组ID"}'

Deleting a group will not delete the environment, and the environment under the original group will become ungrouped. The system default group cannot be deleted.

6. Label API

Tags are used for multiple-choice tagging: up to 20 tags can be bound to an environment, throughtagIdsArray binding.

Tag List

curl --location 'http://127.0.0.1:50325/tag/list' \
  --header 'Content-Type: application/json' \
  --data '{}'

Add tags

curl --location 'http://127.0.0.1:50325/tag/create' \
  --header 'Content-Type: application/json' \
  --data '{"name":"高优先级","color":"#F97316"}'

Edit tags

curl --location 'http://127.0.0.1:50325/tag/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"标签ID","name":"VIP","color":"#A855F7"}'

delete a tap

curl --location 'http://127.0.0.1:50325/tag/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"标签ID"}'

Deleting a tag will unlink it from all environments, but it will not delete the environment.

7. Proxy API

The environment can first create reusable proxies and then transmit themproxyIdIt can also be directly transmitted when creating or updating the environmentproxyThe two methods cannot be used simultaneously.

Proxy list

curl --location 'http://127.0.0.1:50325/proxy/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"search":""}'

Response returns the current proxy passwordpasswordandhasPasswordIt will not return the server ciphertext.

Add new agent

curl --location 'http://127.0.0.1:50325/proxy/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "name":"Tokyo Proxy",
    "protocol":"SOCKS5",
    "host":"proxy.example.com",
    "port":1080,
    "username":"proxy-user",
    "password":"proxy-password"
  }'

Edit Agent

idandproxyIdAgents can be located. omitpasswordKeep the original password and transfer itnullClear password.

curl --location 'http://127.0.0.1:50325/proxy/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"代理ID","host":"new-proxy.example.com","port":1080,"password":"new-password"}'

After modifying the protocol, host, port, username, or password, the detection status will be reset toUNCHECKED.

8. Create an environment

Complete field description

accountsEach item:

inlineproxy：

Complete creation example

curl --location 'http://127.0.0.1:50325/browser/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "name":"完整环境示例",
    "platform":"windows",
    "remark":"通过本地 API 创建",
    "groupId":"分组ID",
    "tagIds":["标签ID1","标签ID2"],
    "accounts":[
      {
        "platform":"google",
        "username":"[email protected]",
        "password":"account-password",
        "totpSecret":null,
        "openOnStart":true,
        "remark":"主账号"
      }
    ],
    "cookies":[
      {
        "name":"session_id",
        "value":"cookie-value",
        "domain":".example.com",
        "path":"/",
        "secure":true,
        "httpOnly":true,
        "sameSite":"Lax"
      }
    ],
    "startupUrls":[
      "https://example.com/login",
      "https://example.com/dashboard"
    ],
    "fingerprint":{
      "timezone":"Asia/Shanghai",
      "acceptLanguage":"zh-CN,zh,en"
    },
    "proxy":{
      "type":"HTTP",
      "host":"proxy.example.com",
      "port":8080,
      "username":"proxy-user",
      "password":"proxy-password"
    }
  }'

Delete when using an existing proxyproxyWhole paragraph, revised transmission'proxyId': 'Proxy ID already exists'When not using a proxy,proxyandproxyIdDon't spread it.

Cookie format

Recommended for usecookiesDirectly transfer JSON array. Common fields for cookies:name、value、domain、path、secure、httpOnly、expirationDate、sameSite.

If usingcookieDataIt must be a string that can be exported as JSON text by browser extensions Netscapecookies.txt, or request header texta=1; b=2.

NonedomainWhen the cookie is started, the domain name can only be inferred based on the first startup URL. It is recommended to explicitly fill it indomain.

9. Update the environment

Updating the interface only modifies the fields sent; Omitting fields remains unchanged. Positioning supportid、profileId、seq、serialNumberTheserial_number.

Coverage rules:

• accountsThe entire group covers,[]Clear all accounts;

• tagIdsThe entire group covers,[]Clear all tags;

• cookiesorcookieDataReplace cookies,nullClearing;

• startupUrlsReplace all startup URLs,[]Clearing;

• groupId:nullDisgrouping;

• proxy:nullorproxyId:nullRelease the proxy.

curl --location 'http://127.0.0.1:50325/browser/update' \
  --header 'Content-Type: application/json' \
  --data '{
    "id":"环境ID",
    "name":"更新后的环境",
    "remark":"完整更新示例",
    "groupId":"分组ID",
    "tagIds":["标签ID"],
    "accounts":[
      {
        "platform":"google",
        "username":"[email protected]",
        "password":"new-password",
        "openOnStart":false
      }
    ],
    "cookies":[
      {
        "name":"session_id",
        "value":"new-cookie-value",
        "domain":".example.com",
        "path":"/"
      }
    ],
    "startupUrls":["https://example.com/dashboard"],
    "proxyId":"已有代理ID"
  }'

Modify the proxy of the running environment Cookie、 After starting the website or fingerprint, first close the environment and then reopen it.

10. Query Environment

Environmental List

curl --location 'http://127.0.0.1:50325/browser/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"name":"","groupId":"分组ID","tagId":"标签ID"}'

Delete unnecessary filtering fields directly.data.listIt is an environment array,data.totalNumIs the total number; Environmental objects includegroupandtags.

Environmental Details

curl --location 'http://127.0.0.1:50325/browser/detail' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

Details returngroup、tags、fingerprint、proxy、accountCount、hasCookieDataEnvironmental owners will also receivecookieData.

11. Delete, Recycle Bin, and Thoroughly Delete

Delete environment to Recycle Bin

curl --location 'http://127.0.0.1:50325/browser/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

If the environment is running, the browser will be closed first and then moved to the recycle bin. This operation can be restored.

Recycle Bin List

curl --location 'http://127.0.0.1:50325/browser/recycle/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"search":"","sort":"desc"}'

Environment in the listidCan be used for recovery or complete deletion.

Restore the environment

curl --location 'http://127.0.0.1:50325/browser/restore' \
  --header 'Content-Type: application/json' \
  --data '{"id":"回收站环境ID"}'

Recovery must use the environment ID, not just the environment serial number.

Completely delete the environment

Single:

curl --location 'http://127.0.0.1:50325/browser/delete/permanent' \
  --header 'Content-Type: application/json' \
  --data '{"id":"回收站环境ID"}'

Batch

curl --location 'http://127.0.0.1:50325/browser/delete/permanent' \
  --header 'Content-Type: application/json' \
  --data '{"ids":["环境ID1","环境ID2"]}'

idsUp to 500. Only environments that are already in the recycle bin will be deleted,data.purgedIt is the actual number of deletions.

Completely deleting is irreversible, and the environment configuration, account, and cookies will be permanently deleted.

12. Open, query, and close the environment

Open the environment

curl --location 'http://127.0.0.1:50325/browser/open' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID","headless":false}'

headlessIt must be a JSON boolean value. Response returnpid、wsThehttp、headless；wsCan be handed over to Playwright or Puppet.

Operating status

curl --location 'http://127.0.0.1:50325/browser/active' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

Parameterless invocation/browser/activeReturn to all running environments. Running list:

curl --location 'http://127.0.0.1:50325/browser/running' \
  --header 'Content-Type: application/json' \
  --data '{}'

PID and CDP ports

curl --location 'http://127.0.0.1:50325/browser/pids' \
  --header 'Content-Type: application/json' \
  --data '{"ids":["环境ID1","环境ID2"]}'

curl --location 'http://127.0.0.1:50325/browser/pids/all' \
  --header 'Content-Type: application/json' \
  --data '{}'

curl --location 'http://127.0.0.1:50325/browser/ports' \
  --header 'Content-Type: application/json' \
  --data '{}'

Close the environment

curl --location 'http://127.0.0.1:50325/browser/close' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

Close all:

curl --location 'http://127.0.0.1:50325/browser/close/all' \
  --header 'Content-Type: application/json' \
  --data '{}'

Closing all will affect all current work windows. Please save the page content before executing.

13. Postman usage

Import the help provided by the Help Center https://www.postman.com/ovo-desktop-api/workspace/ovodesktop-api-example/collection/57777046-8485fa5f-3e60-4da9-8b59-538ae4703339?action=share&source=copy-link&creator=57777046 ：

1. Confirm in the collection VariablesbaseUrl；

2. Run a 'health check';

3. Run the 'Environment List' to confirm that the session has been restored;

4. Each request comes with purpose, field description, complete JSON body, and cURL example;

5. For a complete demonstration, simply run it in folder order without understanding the environment sequence or manually maintaining complex variables;

6. Before executing 'completely delete environment', confirm that the target is a test environment that allows permanent deletion.

14. Common errors