Browser Sessions

Persisted Stagehand auth sessions.

8 actions. Each is callable by the agent as a tool, over HTTP via /api/invoke, and (usually) from a UI page.

browser_sessions.list

GET

List browser sessions — Stagehand-driven authenticated sessions saved per (platform, subject). Use to discover which platforms the user has already authenticated against via the browser auth flow.

• AI tool: browser_sessions_list
• API: GET /api/invoke/browser_sessions.list

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "platform": {
      "type": "string"
    },
    "subjectId": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "active",
        "expired",
        "revoked"
      ]
    }
  }
}

browser_sessions.get

GET

Get one browser session by id (does not include the encrypted cookie blob).

• AI tool: browser_sessions_get
• API: GET /api/invoke/browser_sessions.get

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

browser_sessions.login_start

POST · mutating

Start an interactive Stagehand login session for a platform. Opens the browser at the platform's login URL; if Browserbase is configured, returns a live view URL the user can watch + interact with in the UI. When they finish logging in, call browser_sessions.login_finish to capture + persist the cookies.

• AI tool: browser_sessions_login_start
• API: POST /api/invoke/browser_sessions.login_start

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "platform": {
      "type": "string"
    },
    "subjectId": {
      "type": "string",
      "minLength": 1
    },
    "loginUrl": {
      "type": "string",
      "format": "uri"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "platform"
  ]
}

browser_sessions.login_finish

POST · mutating

Capture cookies + localStorage from a pending login session, encrypt, persist. After this the session is reusable by publishers.

• AI tool: browser_sessions_login_finish
• API: POST /api/invoke/browser_sessions.login_finish

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "sessionId"
  ]
}

browser_sessions.import_cookies

POST · mutating

LOCAL-mode escape hatch: paste a Playwright storageState JSON (or an array of cookies from a browser extension like EditThisCookie / Cookie-Editor) directly, skipping the interactive Stagehand login. Useful when Browserbase isn't configured so the embedded login view doesn't work. The session is created already-active and ready for publishing.

When the agent calls it: Use this when the user has no Browserbase set up. Tell them: "Open Kickstarter in your normal browser, install a cookie-export extension like Cookie-Editor, click Export → JSON, and paste it here." That avoids the need for an embedded login.

• AI tool: browser_sessions_import_cookies
• API: POST /api/invoke/browser_sessions.import_cookies

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "platform": {
      "type": "string"
    },
    "subjectId": {
      "type": "string",
      "minLength": 1
    },
    "name": {
      "type": "string"
    },
    "storageState": {},
    "expiresAt": {}
  },
  "required": [
    "platform",
    "storageState"
  ]
}

browser_sessions.delete

DELETE · mutating

Delete a saved browser session (revoke). Does NOT log out on the platform — cookies may still be valid until expiry.

• AI tool: browser_sessions_delete
• API: DELETE /api/invoke/browser_sessions.delete

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

browser_sessions.update

PATCH · mutating

Re-tie a saved browser session to a different subject scope, or rename it. Useful when a connection was made workspace-wide and you want to scope it to a specific subject (or vice versa) without re-running the interactive login. Pass subjectId=null to move the session back to workspace-wide scope.

• AI tool: browser_sessions_update
• API: PATCH /api/invoke/browser_sessions.update

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "name": {
      "type": "string"
    },
    "subjectId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "id"
  ]
}

browser_sessions.test

POST · mutating

Verify a saved session's cookies still log the user in. Loads them into a fresh Stagehand context, navigates to a known authenticated URL, checks whether the redirect went to a login page (expired) or the user's home (active), and extracts the logged-in account's username/handle so the UI can show "logged in as @handle". The extracted handle is persisted on the session metadata.

• AI tool: browser_sessions_test
• API: POST /api/invoke/browser_sessions.test

Input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "testUrl": {
      "type": "string",
      "format": "uri"
    },
    "skipUsername": {
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ]
}