API Request Parameter Examples

This document provides common request examples for client integration testing.

1. Login to Obtain Auth Token

POST /api/member/login
Content-Type: application/json

{
  "account": "user@example.com",
  "password": "password"
}

After success, retrieve the auth token from the returned data.auth.

It is recommended to include the following in subsequent requests:

Authorization: Bearer {auth}
Content-Type: application/json

2. Query Current Account Permissions

POST /api/sysUsers/permissions
Authorization: Bearer {auth}
Content-Type: application/json

{}

Key fields in the response:

{
  "data": {
    "isMainAccount": false,
    "permissionCodes": [
      "browser:list",
      "browser:create:single",
      "browser:update:single",
      "browser:update:batch",
      "group:list",
      "group:add"
    ]
  },
  "code": 0,
  "msg": "success"
}

3. Create a Group

POST /group/add
Authorization: Bearer {auth}
Content-Type: application/json

{
  "groupName": "Amazon Store",
  "sortNum": 0
}

4. Query Group List

POST /group/list
Authorization: Bearer {auth}
Content-Type: application/json

{
  "page": 0,
  "pageSize": 100
}

5. Create a Tag

POST /browserTag/create
Authorization: Bearer {auth}
Content-Type: application/json

{
  "tagName": "Key Account",
  "tagColor": "#ECC2F3"
}

6. Query Tag List

POST /browserTag/list
Authorization: Bearer {auth}
Content-Type: application/json

{
  "keyword": ""
}

7. Create a Browser Window

POST /browser/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "name": "Amazon-001",
  "groupId": 12,
  "tagIds": [3, 5],
  "remark": "Created by client",
  "browserFingerPrint": {
    "coreVersion": "118",
    "ostype": "PC",
    "os": "Win32"
  },
  "proxyMethod": 2,
  "proxyType": "direct"
}

Note: The above is a simplified creation example using the cloud API. When creating a window via the Local API through /browser/update, it has been verified that a complete, non-empty config object is required.

8. Create a Window with HTTP Proxy

POST /browser/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "name": "HTTP Proxy Window",
  "groupId": 12,
  "proxyMethod": 2,
  "proxyType": "http",
  "host": "127.0.0.1",
  "port": 7890,
  "proxyUserName": "",
  "proxyPassword": "",
  "browserFingerPrint": {}
}

9. Query Window List

POST /browser/list
Authorization: Bearer {auth}
Content-Type: application/json

{
  "page": 0,
  "pageSize": 20,
  "groupId": 12
}

10. Query Window Details

POST /browser/detail
Authorization: Bearer {auth}
Content-Type: application/json

{
  "id": 101
}

Alternatively, you can pass:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Note: When querying window details via the Local API, it is recommended to use uuid; using a numeric id may return 'UUID invalid'.

11. Batch Update Window Name, Group, Remark, and Tags

POST /browser/update/partial
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102],
  "name": "Batch rename",
  "groupId": 15,
  "remark": "New remark",
  "tagIds": [3, 8]
}

12. Batch Update Window Group

POST /browser/group/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102],
  "groupId": 15
}

13. Batch Update Window Remark

POST /browser/remark/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102],
  "remark": "This is a new remark"
}

14. Batch Update Window Proxy

POST /browser/proxy/update
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102],
  "ipCheckService": "ip-api",
  "proxyMethod": 2,
  "proxyType": "socks5",
  "host": "127.0.0.1",
  "port": 1080,
  "proxyUserName": "user",
  "proxyPassword": "pass",
  "refreshProxyUrl": ""
}

15. Add or Remove Tags from Windows

POST /browserTag/updateRelation
Authorization: Bearer {auth}
Content-Type: application/json

{
  "browserId": 101,
  "addTagIds": [3],
  "removeTagIds": [5]
}

Local API recommends using uuid:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "addTagIds": [3],
  "removeTagIds": [5]
}

Note: When updating tag bindings via the Local API, it is recommended to use uuid; using a numeric browserId may return 'UUID invalid'.

16. Delete Windows

POST /browser/delete
Authorization: Bearer {auth}
Content-Type: application/json

{
  "id": 101
}

Batch delete:

POST /browser/delete/ids
Authorization: Bearer {auth}
Content-Type: application/json

{
  "ids": [101, 102]
}

Note: The first stage of deletion moves the window to the recycle bin by default.

17. Open and Close Windows (Local API)

POST http://127.0.0.1:54345/browser/open
X-Cos-Local-Token: <local access token>
Content-Type: application/json

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

POST http://127.0.0.1:54345/browser/close
X-Cos-Local-Token: <local access token>
Content-Type: application/json

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Note: The Local API only listens on 127.0.0.1; the actual port and access token should be taken from the client's 'System Settings / Local API' page.

18. Common Failure Responses

Not logged in:

{
  "code": 401,
  "msg": "auth required",
  "data": {}
}

Login expired:

{
  "code": 401,
  "msg": "auth expired",
  "data": {}
}

No permission:

{
  "code": 403,
  "msg": "permission denied",
  "data": {}
}

Parameter error:

{
  "code": 211,
  "msg": "browser id required",
  "data": {}
}