API Evangelist conversational phrasing for Browser Use Sessions API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Browser Use Sessions API
  version: 1.0.0
extends: openapi/browser-use-sessions-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 15
- target: $.paths['/sessions'].get
  update:
    x-apievangelist-phrasing:
      intent: List AI agent sessions
      effect: read
      questions:
      - Which AI agent sessions are currently active in my project?
      - Can I filter my agent sessions by status and page through them?
      instructions:
      - text: List my agent sessions with status {status}.
        slots:
          status: query.filterBy
      - text: Show page {page} of my agent sessions, {size} at a time.
        slots:
          page: query.pageNumber
          size: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a new AI agent session
      effect: write
      questions:
      - How do I open an agent session that I can send several tasks to in turn?
      - Can a new agent session start on a given URL and use a saved browser profile?
      - Is there a way to keep an agent session alive between tasks?
      instructions:
      - text: Start an agent session at {start_url} using profile {profile}.
        slots:
          start_url: requestBody.startUrl
          profile: requestBody.profileId
      - text: Open an agent session with a {country} proxy and keep-alive set to {keep_alive}.
        slots:
          country: requestBody.proxyCountryCode
          keep_alive: requestBody.keepAlive
      - text: Create an agent session with persistent memory {persist}.
        slots:
          persist: requestBody.persistMemory
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an agent session's status and tasks
      effect: read
      questions:
      - What's the live URL and current status of my agent session?
      - Which tasks has an agent session run so far?
      instructions:
      - text: Show the details and task list of agent session {session_id}.
        slots:
          session_id: path.session_id
      - text: Get the live URL for agent session {session_id}.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an agent session and its tasks
      effect: destructive
      questions:
      - How do I delete an agent session together with every task in it?
      - What gets removed when I delete an agent session?
      instructions:
      - text: Delete agent session {session_id} and all of its tasks.
        slots:
          session_id: path.session_id
      - text: Remove session {session_id} from my project entirely.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Stop a session via the update action
      effect: destructive
      questions:
      - Can I stop an agent session and all its running tasks by updating the session with an action?
      - Is stopping a session through the update endpoint reversible?
      instructions:
      - text: Update agent session {session_id} with action {action} to halt it and every running task.
        slots:
          session_id: path.session_id
          action: requestBody.action
      - text: Send the stop action to session {session_id} through the session update endpoint.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/purge'].post
  update:
    x-apievangelist-phrasing:
      intent: Purge all stored data for a session
      effect: destructive
      questions:
      - How do I immediately wipe screenshots, logs and files for a session on a zero-data-retention project?
      - Can I redact personal data from one session now instead of waiting for the scheduled cleanup?
      instructions:
      - text: Purge every stored object and redact PII for session {session_id} right now.
        slots:
          session_id: path.session_id
      - text: Run the zero-data-retention cleanup on session {session_id} with no grace period.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/public-share'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a session's public share link and stats
      effect: read
      questions:
      - What's the public share URL for a session I already shared?
      - How many times has my shared session link been viewed?
      instructions:
      - text: Show the existing public share link and usage stats for session {session_id}.
        slots:
          session_id: path.session_id
      - text: Check the view statistics on the shared replay of session {session_id}.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/public-share'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a public share link for a session
      effect: write
      questions:
      - How can I share a replay of an agent session with someone who doesn't have an account?
      - Can I make an agent session publicly viewable?
      instructions:
      - text: Create a public share link for session {session_id}.
        slots:
          session_id: path.session_id
      - text: Make session {session_id} public so I can send the link to a colleague.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/public-share'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a session's public share link
      effect: destructive
      questions:
      - How do I stop a session from being publicly viewable?
      - Can I take down the public link I created for a session?
      instructions:
      - text: Remove the public share from session {session_id}.
        slots:
          session_id: path.session_id
      - text: Unshare session {session_id} so the public link stops working.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/stop'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop a session or only its running task
      effect: destructive
      questions:
      - Can I stop just the query an agent is running while leaving the session idle and alive?
      - How do I destroy a session's sandbox entirely using the dedicated stop endpoint?
      instructions:
      - text: Use the stop endpoint to destroy the sandbox for session {session_id}.
        slots:
          session_id: path.session_id
      - text: Halt whatever session {session_id} is doing right now but keep it idle for my next message.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a session's message history
      effect: read
      questions:
      - How can I read the conversation between me and the agent in a session?
      - Can I page through a session's messages before or after a given point?
      instructions:
      - text: Show the messages in session {session_id} after {after}.
        slots:
          session_id: path.session_id
          after: query.after
      - text: List the last {limit} messages of session {session_id} before {before}.
        slots:
          limit: query.limit
          session_id: path.session_id
          before: query.before
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/queue'].get
  update:
    x-apievangelist-phrasing:
      intent: View a session's pending message queue
      effect: read
      questions:
      - Which of my follow-up messages are still waiting in a session's queue?
      - Can I see the steering handoffs and interrupt cutoffs for a session?
      instructions:
      - text: Show the open queued messages and steering cutoffs for session {session_id}.
        slots:
          session_id: path.session_id
      - text: List what is waiting in the queue of session {session_id}.
        slots:
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/queue'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a follow-up message to a session
      effect: write
      questions:
      - How do I give an agent a follow-up instruction while it's still busy?
      - Can a new message interrupt the agent's current run instead of waiting its turn?
      instructions:
      - text: 'Tell the agent in session {session_id}: {text}.'
        slots:
          session_id: path.session_id
          text: requestBody.text
      - text: 'Interrupt session {session_id} and have it do this instead: {text} (interrupt {interrupt}).'
        slots:
          session_id: path.session_id
          text: requestBody.text
          interrupt: requestBody.interrupt
      - text: Send {text} to session {session_id} with files {files} attached.
        slots:
          text: requestBody.text
          session_id: path.session_id
          files: requestBody.attachedFileIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/queue/{message_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check one queued message's status
      effect: read
      questions:
      - Has the follow-up message I queued been picked up by the agent yet?
      - What happened to a specific message I sent to a session's queue?
      instructions:
      - text: Show queued message {message_id} in session {session_id}.
        slots:
          message_id: path.message_id
          session_id: path.session_id
      - text: Check whether message {message_id} in session {session_id} was handed off.
        slots:
          message_id: path.message_id
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sessions/{session_id}/queue/{message_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a message still waiting in the queue
      effect: destructive
      questions:
      - Can I take back a follow-up message before the agent starts on it?
      - Why would cancelling a queued message fail after the agent has claimed it?
      instructions:
      - text: Cancel queued message {message_id} in session {session_id}.
        slots:
          message_id: path.message_id
          session_id: path.session_id
      - text: Withdraw pending message {message_id} from session {session_id} before it runs.
        slots:
          message_id: path.message_id
          session_id: path.session_id
      method: generated
      generated: '2026-09-26'