Automation Sessions

Create and close automation sessions, read session details, manage tabs, list the account candidates for the current page, fill vault or caller-supplied credentials, and run actions. Every request in one automation flow must send the same X-Nex-Client-Id.

For the action names and fields that POST /automation/sessions/:sessionId/actions accepts, see the automation action allowlist. CAPTCHA actions also need the X-Nex-Service-Context header; see Service and authentication for its value.

Search this page

Showing 11 of 11 endpoints

POST/automation/sessions

Create automation session

Creates an automation session for a browser window, owned exclusively by the current client and bound to X-Nex-Client-Id.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
windowId	string	Required	Browser window ID
teamId	string	Optional	Team ID, defaults to the current team
startIfNeeded	boolean	Optional	When true, starts the window first if it is not running, default false

Notes

• Returns WINDOW_NOT_RUNNING if the window is not running and startIfNeeded is not true.
• The session records the account and team context at creation; after the signed-in account or team changes, the old session returns UNAUTHORIZED.

Response fields

Field	Type	Description
data.clientId	string	Client that owns the session, taken from X-Nex-Client-Id
data.sessionId	string	Session ID, used as the path parameter in subsequent endpoints
data.teamId	string	ID of the team the session belongs to
data.windowId	string	ID of the window bound to the session
data.activePageId	string	Current active tab ID, omitted when there are no tabs
data.tabs	object[]	Current tab list
data.tabs[].pageId	string	Tab ID, stable within the session
data.tabs[].title	string	Page title, empty string if it cannot be read
data.tabs[].url	string	Page URL
data.tabs[].active	boolean	Whether this is the session's current active tab
data.createdAt	number	Session creation timestamp, milliseconds
data.lastActivityAt	number	Last activity timestamp, milliseconds

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "clientId": "nex-doc-client-01",
    "sessionId": "a1f0c7d2-3b6e-4c58-9a1d-77e0b3c9f412",
    "teamId": "2001",
    "windowId": "8001",
    "activePageId": "page-1",
    "tabs": [
      {
        "pageId": "page-1",
        "title": "Example Domain",
        "url": "https://example.com/",
        "active": true
      }
    ],
    "createdAt": 1786000000000,
    "lastActivityAt": 1786000000000
  }
}

DELETE/automation/sessions

Close all client sessions

Releases all automation sessions owned by the current X-Nex-Client-Id without closing the underlying browser windows.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

None

Notes

• Call this before the MCP client exits so sessions do not sit idle until the idle timeout.

Response fields

Field	Type	Description
data.closed	boolean	Always true

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "closed": true
  }
}

GET/automation/sessions/:sessionId

Get automation session

Reads the ownership info and live tab list of a session owned by the current client.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
sessionId	string	Required	Automation session ID

Response fields

Field	Type	Description
data.clientId	string	Client that owns the session, taken from X-Nex-Client-Id
data.sessionId	string	Session ID, used as the path parameter in subsequent endpoints
data.teamId	string	ID of the team the session belongs to
data.windowId	string	ID of the window bound to the session
data.activePageId	string	Current active tab ID, omitted when there are no tabs
data.tabs	object[]	Current tab list
data.tabs[].pageId	string	Tab ID, stable within the session
data.tabs[].title	string	Page title, empty string if it cannot be read
data.tabs[].url	string	Page URL
data.tabs[].active	boolean	Whether this is the session's current active tab
data.createdAt	number	Session creation timestamp, milliseconds
data.lastActivityAt	number	Last activity timestamp, milliseconds

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "clientId": "nex-doc-client-01",
    "sessionId": "a1f0c7d2-3b6e-4c58-9a1d-77e0b3c9f412",
    "teamId": "2001",
    "windowId": "8001",
    "activePageId": "page-2",
    "tabs": [
      {
        "pageId": "page-1",
        "title": "Example Domain",
        "url": "https://example.com/",
        "active": false
      },
      {
        "pageId": "page-2",
        "title": "X",
        "url": "https://x.com/",
        "active": true
      }
    ],
    "createdAt": 1786000000000,
    "lastActivityAt": 1786000042000
  }
}

DELETE/automation/sessions/:sessionId

Close automation session

Releases an automation session without closing the underlying browser window.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
sessionId	string	Required	Automation session ID

Response fields

Field	Type	Description
data.closed	boolean	Always true

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "closed": true
  }
}

GET/automation/sessions/:sessionId/tabs

List tabs

Lists the stable pageIds in the session; closed pages are cleaned up during this call.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
sessionId	string	Required	Automation session ID

Response fields

Field	Type	Description
data	object[]	List tabs
data[].pageId	string	Tab ID, stable within the session
data[].title	string	Page title, empty string if it cannot be read
data[].url	string	Page URL
data[].active	boolean	Whether this is the session's current active tab

Response example

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "pageId": "page-1",
      "title": "Example Domain",
      "url": "https://example.com/",
      "active": true
    }
  ]
}

POST/automation/sessions/:sessionId/tabs

Open new tab

Opens a new tab in the session and makes it active, optionally navigating to a given URL.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
sessionId	string	Required	Automation session ID
url	string	Optional	Optional initial URL; navigation timeout follows the session's navigation timeout setting

Response fields

Field	Type	Description
data	object[]	Full tab list after creation
data[].pageId	string	Tab ID, stable within the session
data[].title	string	Page title, empty string if it cannot be read
data[].url	string	Page URL
data[].active	boolean	Whether this is the session's current active tab

Response example

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "pageId": "page-1",
      "title": "X",
      "url": "https://x.com/",
      "active": false
    },
    {
      "pageId": "page-2",
      "title": "Example Domain",
      "url": "https://example.com/",
      "active": true
    }
  ]
}

POST/automation/sessions/:sessionId/tabs/select

Select active tab

Changes only the current session's active tab; other clients' sessions are not affected.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
sessionId	string	Required	Automation session ID
pageId	string	Required	Target tab ID; returns PAGE_NOT_FOUND if it does not exist

Response fields

Field	Type	Description
data	object[]	Full tab list after switching
data[].pageId	string	Tab ID, stable within the session
data[].title	string	Page title, empty string if it cannot be read
data[].url	string	Page URL
data[].active	boolean	Whether this is the session's current active tab

Response example

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "pageId": "page-1",
      "title": "X",
      "url": "https://x.com/",
      "active": true
    },
    {
      "pageId": "page-2",
      "title": "Example Domain",
      "url": "https://example.com/",
      "active": false
    }
  ]
}

POST/automation/sessions/:sessionId/tabs/close

Close tab

Closes one stable pageId in the current session and returns the tab list after closing.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
sessionId	string	Required	Automation session ID
pageId	string	Required	Target tab ID; returns PAGE_NOT_FOUND if it does not exist

Response fields

Field	Type	Description
data	object[]	Full tab list after closing
data[].pageId	string	Tab ID, stable within the session
data[].title	string	Page title, empty string if it cannot be read
data[].url	string	Page URL
data[].active	boolean	Whether this is the session's current active tab

Response example

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "pageId": "page-1",
      "title": "X",
      "url": "https://x.com/",
      "active": true
    }
  ]
}

POST/automation/sessions/:sessionId/account_candidates

List account candidates

Lists the login entries available for the current page, for choosing among multiple accounts; read-only, does not fill, and excludes passwords and 2FA secrets.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
sessionId	string	Required	Automation session ID
pageId	string	Optional	Target tab ID, defaults to the active tab

Notes

• Candidates are computed by the vault extension for the target page, unlike /browser/accounts, which returns the entire vault.
• The call makes the target tab active; returns WINDOW_NOT_RUNNING if the vault session is unavailable.

Response fields

Field	Type	Description
data.windowId	string	ID of the window bound to the session
data.host	string	Hostname of the target tab
data.candidates	object[]	Login entries matching the current page
data.candidates[].credentialId	string	Entry ID, used as accountId for account_fill
data.candidates[].username	string	Entry username
data.candidates[].name	string	Entry name

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "windowId": "8001",
    "host": "x.com",
    "candidates": [
      {
        "credentialId": "platform:5001",
        "username": "de**********nt",
        "name": "x.com"
      },
      {
        "credentialId": "local:2",
        "username": "op******01",
        "name": "x.com"
      }
    ]
  }
}

POST/automation/sessions/:sessionId/account_fill

Fill window login account

Fills a vault entry or caller-supplied credentials into the visible login fields on the current page; fills without submitting, and the response excludes passwords and 2FA secrets.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
sessionId	string	Required	Automation session ID
accountId	string	Optional	Vault entry ID, from credentialId in account_candidates or accountId in /browser/accounts
username	string	Optional	Selects by username among the entries matching the current page, used when accountId is not passed
credentials	object	Optional	Login credentials outside the vault, used for this call only
credentials.username	string	Optional	Username
credentials.password	string	Optional	Login password, used as-is with leading and trailing spaces preserved
credentials.totp	string	Optional	2FA secret; the extension generates the code
credentials.totpCode	string	Optional	Pre-generated one-time code, filled in as-is
pageId	string	Optional	Target tab ID, defaults to the active tab

Notes

• The vault extension selects the entry based on the currently open page: only login entries that match the page are considered.
• If multiple entries match and neither accountId nor username is specified, returns INVALID_ARGUMENT; data.candidates lists the candidate entries (credentialId, username, name) and data.code is the extension result code (e.g. ambiguous, noMatch). Retry with accountId.
• credentials are used only for this fill; they are not stored, echoed, or logged, and never appear in error messages.
• Returns WINDOW_NOT_RUNNING if the vault session is unavailable (window not open or extension not ready).
• usernameTarget, passwordTarget, and totpTarget are no longer accepted; the vault extension selects the visible login fields on the current page.
• Vault passwords and 2FA secrets are used only inside the extension and never appear in the request body or response. This endpoint fills without submitting.

Response fields

Field	Type	Description
data.windowId	string	ID of the window bound to the session
data.accountId	string	ID of the entry the extension actually filled
data.platformName	string	Entry name
data.username	string	Entry username returned by the extension
data.filled	string[]	Credential items actually filled: username, password, totp
data.submitted	boolean	Always false; this endpoint does not submit the form

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "windowId": "8001",
    "accountId": "5001",
    "platformName": "x.com",
    "username": "de**********nt",
    "filled": [
      "username",
      "password"
    ],
    "submitted": false
  }
}

POST/automation/sessions/:sessionId/actions

Run automation action

Picks an action from a fixed allowlist and adds it to the session's serial execution queue; see the action list further down the page.

AuthBearer API KeyX-Nex-Client-Id

Request parameters

Field	Type	Required	Description
sessionId	string	Required	Automation session ID
action	string	Required	Action name, see the "Automation actions" allowlist; returns ACTION_NOT_ALLOWED if not in the allowlist
pageId	string	Optional	Target tab ID, defaults to the active tab
params	object	Optional	Action-specific parameters
params.timeout	number	Optional	General timeout, range 1..120000 milliseconds
params.snapshot	string | boolean	Optional	Granularity of the snapshot returned after the action: none returns nothing, refs returns element refs only, full returns the full snapshot; interaction actions default to refs, the snapshot action defaults to full; false equals none, true equals full
X-Nex-Service-Context	header	Optional	Required for CAPTCHA actions, the contextId from the business endpoint's response
X-Nex-Request-Deadline	header	Optional	Optional for CAPTCHA actions, request deadline as a millisecond timestamp

Notes

• The three data fields appear by action type: read actions use result, snapshot actions use snapshot, and screenshot and download actions use artifacts.
• captchaInspect, captchaRefresh, and captchaApply require the X-Nex-Service-Context header; sign-in and team are re-verified before and after execution, and UNAUTHORIZED is returned if either has changed.
• If the caller disconnects while the action is queued, CAPTCHA actions are no longer dispatched to the page.
• Failures with registered error codes are all reported as INVALID_ARGUMENT with msg in Chinese; data does not include the server business code.

Response fields

Field	Type	Description
data.result	any	Action return value; its shape depends on the action (text, boolean, array, etc.)
data.result.path	string	screenshot action: local path of the screenshot file
data.result.region	object	screenshot action: x, y, width, height of the captured area in viewport CSS pixel coordinates, convertible back to click coordinates
data.snapshot	string	Page structure snapshot text; navigation and interaction actions include only the element refs section by default, adjustable via params.snapshot
data.artifacts	object[]	Artifact list, returned by screenshot and download actions
data.artifacts[].kind	string	Artifact type: screenshot, download, trace
data.artifacts[].path	string	Local path of the artifact
data.artifacts[].mimeType	string	Artifact MIME type
data.artifacts[].size	number	Artifact size in bytes
data.artifacts[].base64	string	Artifact content in Base64, returned depending on the action parameters

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "result": null
  }
}