openapi: 3.1.0
info:
  title: Computer-Use Agents Schedules API
  version: 1.0.0
servers:
- url: https://agp.eu.hcompany.ai
  description: Europe
  x-fern-server-name: Eu
- url: https://agp.hcompany.ai
  description: United States
  x-fern-server-name: Us
tags:
- name: Schedules
paths:
  /api/v2/schedules:
    post:
      tags:
      - Schedules
      summary: Create Schedule
      description: Create a schedule that starts a session on each fire.
      operationId: create_schedule_api_v2_schedules_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSchedule'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Schedules
      summary: List Schedules
      description: List the organization's schedules.
      operationId: list_schedules_api_v2_schedules_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Number of items per page
          default: 10
          title: Size
        description: Number of items per page
      - name: sort
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              enum:
              - created_at
              - -created_at
              type: string
          - type: 'null'
          description: Sort by field
          default:
          - -created_at
          title: Sort
        description: Sort by field
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_ScheduleRecord_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/schedules/{schedule_id}:
    get:
      tags:
      - Schedules
      summary: Get Schedule
      description: Fetch a schedule by id.
      operationId: get_schedule_api_v2_schedules__schedule_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Schedules
      summary: Update Schedule
      description: Update a schedule; only provided fields change. Timing changes recompute the next fire.
      operationId: update_schedule_api_v2_schedules__schedule_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Schedule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSchedule'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Schedules
      summary: Delete Schedule
      description: Delete a schedule. Future fires stop; sessions already created keep running.
      operationId: delete_schedule_api_v2_schedules__schedule_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Schedule Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/schedules/{schedule_id}/pause:
    post:
      tags:
      - Schedules
      summary: Pause Schedule
      description: Pause a schedule with an optional note.
      operationId: pause_schedule_api_v2_schedules__schedule_id__pause_post
      security:
      - HTTPBearer: []
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Schedule Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/PauseSchedule'
              - type: 'null'
              title: Pause
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/schedules/{schedule_id}/resume:
    post:
      tags:
      - Schedules
      summary: Resume Schedule
      description: Resume a paused schedule; the next fire is recomputed from now.
      operationId: resume_schedule_api_v2_schedules__schedule_id__resume_post
      security:
      - HTTPBearer: []
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/schedules/{schedule_id}/trigger:
    post:
      tags:
      - Schedules
      summary: Trigger Schedule
      description: Fire the schedule once now (works while paused); the regular cadence is unaffected.
      operationId: trigger_schedule_api_v2_schedules__schedule_id__trigger_post
      security:
      - HTTPBearer: []
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleRunRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/schedules/{schedule_id}/runs:
    get:
      tags:
      - Schedules
      summary: List Schedule Runs
      description: List the schedule's recent run outcomes, newest fire first.
      operationId: list_schedule_runs_api_v2_schedules__schedule_id__runs_get
      security:
      - HTTPBearer: []
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Schedule Id
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Number of items per page
          default: 10
          title: Size
        description: Number of items per page
      - name: sort
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              enum:
              - scheduled_for
              - -scheduled_for
              type: string
          - type: 'null'
          description: Sort by field
          default:
          - -scheduled_for
          title: Sort
        description: Sort by field
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_ScheduleRunRecord_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Desktop:
      properties:
        id:
          type: string
          minLength: 1
          title: Id
          description: Catalog identifier for this environment.
        kind:
          type: string
          const: desktop
          title: Kind
          default: desktop
        host:
          type: string
          title: Host
          const: user_device
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
          description: Connect to an existing desktop session by id instead of starting a new one.
      type: object
      required:
      - id
      - host
      title: Desktop
      description: A desktop the agent controls via mouse, keyboard, and screenshots.
    CronTiming:
      properties:
        type:
          type: string
          const: cron
          title: Type
          default: cron
        expression:
          type: string
          title: Expression
          description: Five-field cron expression, e.g. '0 9 * * 1-5'.
        timezone:
          type: string
          title: Timezone
          description: IANA timezone the expression is evaluated in, e.g. 'Europe/Paris'.
      type: object
      required:
      - expression
      - timezone
      title: CronTiming
      description: Cron cadence evaluated in an IANA timezone.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ProxyPool:
      type: string
      enum:
      - residential
      - datacenter
      - isp
      - mobile
      title: ProxyPool
      description: The kind of upstream IPs a managed proxy draws from.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SessionRequest:
      properties:
        agent:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/Agent'
          title: Agent
          description: 'Agent to run: a registered agent''s name, or an inline Agent definition.'
        messages:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/UserMessageEvent'
          - items:
              $ref: '#/components/schemas/UserMessageEvent'
            type: array
          - type: 'null'
          title: Messages
          description: Initial task for the agent. A plain string, a single message, or a list of messages.
        max_steps:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Steps
          description: Maximum reasoning steps the agent may take. Unbounded if null.
        max_time_s:
          anyOf:
          - type: number
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Max Time S
          description: Maximum wall-clock seconds the agent may run. Unbounded if null.
        idle_timeout_s:
          anyOf:
          - type: integer
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Idle Timeout S
          description: Seconds to keep the session open for follow-up messages after each answer. Null ends the session as soon as the agent answers.
        delete_after_min:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Delete After Min
          description: Minutes after the session finishes before it is automatically deleted. Defaults to 30 days. Null keeps the session forever.
          default: 43200
        delete_screenshot_after_min:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Delete Screenshot After Min
          description: Minutes after the session finishes before its screenshots are deleted. Defaults to 30 days. Null keeps screenshots for the session's lifetime.
          default: 43200
        queue:
          type: boolean
          title: Queue
          description: When the organization is at its concurrent-session limit, accept this session into a queue (status 'queued') instead of rejecting it with 429. Queued sessions start automatically, oldest first, as running sessions finish. Set to false to get an immediate 429 when no slot is available.
          default: true
        group_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Id
          description: Optional id to group and list related sessions together.
        parent_session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Session Id
          description: Id of the parent session, when this is a child run.
        overrides:
          additionalProperties: true
          type: object
          title: Overrides
          description: 'Per-run overrides applied to the resolved request, keyed by a dotted path. List members are selected with an explicit [field=value] clause, e.g. {"agent.environments[kind=web].start_url": "https://bing.com"}. Each value must match the type of the field its path targets.'
      type: object
      required:
      - agent
      title: SessionRequest
      description: '``POST /api/v2/sessions`` body.'
    UpdateSchedule:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Description
        timing:
          anyOf:
          - $ref: '#/components/schemas/CronTiming'
          - type: 'null'
        session_request:
          anyOf:
          - $ref: '#/components/schemas/SessionRequest'
          - type: 'null'
      type: object
      title: UpdateSchedule
      description: Partial update; omit a field to leave it unchanged.
    Page_ScheduleRunRecord_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ScheduleRunRecord'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
      type: object
      required:
      - items
      - total
      - page
      title: Page[ScheduleRunRecord]
    Environment:
      oneOf:
      - $ref: '#/components/schemas/Browser'
      - $ref: '#/components/schemas/Desktop'
      discriminator:
        propertyName: kind
        mapping:
          desktop: '#/components/schemas/Desktop'
          web: '#/components/schemas/Browser'
    BrowserVisualMode:
      properties:
        type:
          type: string
          const: visual
          title: Type
          default: visual
        width:
          type: integer
          exclusiveMinimum: 0.0
          title: Width
          description: Viewport width in pixels.
          default: 1200
        height:
          type: integer
          exclusiveMinimum: 0.0
          title: Height
          description: Viewport height in pixels.
          default: 1200
        markdown:
          type: boolean
          title: Markdown
          description: Also include the viewport's text as markdown alongside each screenshot.
          default: false
      type: object
      title: BrowserVisualMode
      description: Act on screenshots by viewport coordinates.
    ScheduleRunRecord:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        schedule_id:
          type: string
          format: uuid
          title: Schedule Id
        status:
          type: string
          enum:
          - created
          - skipped_overlap
          - skipped_quota
          - error
          title: Status
        scheduled_for:
          type: string
          format: date-time
          title: Scheduled For
        session_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Session Id
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        triggered_manually:
          type: boolean
          title: Triggered Manually
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - schedule_id
      - status
      - scheduled_for
      - session_id
      - error
      - triggered_manually
      - created_at
      title: ScheduleRunRecord
      description: Outcome of one schedule fire.
    Agent:
      properties:
        name:
          type: string
          maxLength: 127
          minLength: 1
          title: Name
          description: 'Unique name for this agent in your catalog. Format: lowercase ASCII letters, digits and hyphens; must start and end with alphanumeric; max 63 chars per segment; optional single ''org/'' namespace prefix (e.g. ''h/web-environment'').'
        description:
          type: string
          minLength: 1
          title: Description
          description: What the agent does. Parent agents read this to decide when to delegate to it.
        environments:
          items:
            anyOf:
            - type: string
            - $ref: '#/components/schemas/Environment'
          type: array
          title: Environments
          description: Environments the agent runs in. Each entry is a registered environment's id or an inline definition. At most one per kind. Required unless the agent delegates to subagents (a pure orchestrator owns none).
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Model that serves the agent. Defaults to the platform model if omitted.
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
          description: Instructions appended to the agent's system prompt to steer behavior.
        subagents:
          anyOf:
          - items:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/Agent'
            type: array
          - type: 'null'
          title: Subagents
          description: Agents this one can delegate to. Each entry is a registered agent's name or an inline definition.
        skills:
          anyOf:
          - items:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/Skill'
            type: array
          - type: 'null'
          title: Skills
          description: Skills the agent can draw on. Each entry is a registered skill's name or an inline definition.
        answer_format:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Answer Format
          description: JSON Schema the agent's final answer must conform to. Null returns a free-form text answer.
        tools:
          anyOf:
          - items:
              $ref: '#/components/schemas/ToolDefinition'
            type: array
          - type: 'null'
          title: Tools
          description: Custom tools executed by the API client. The agent emits a tool call, pauses, and resumes once the client sends back the matching tool result.
      type: object
      required:
      - name
      - description
      - environments
      title: Agent
      description: Declarative agent definition.
    BrowserNetwork:
      properties:
        proxy_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Proxy Url
          description: Optional bring-your-own HTTP/HTTPS/SOCKS proxy URL for browser egress (e.g. http://user:pass@proxy.example.com:8080). Applied when provisioning a new remote browser session. Only supported for chromium-based browser runners (headful and headless). Ignored when session_id attaches to an existing session. Mutually exclusive with managed_proxy.
        managed_proxy:
          anyOf:
          - $ref: '#/components/schemas/ManagedProxySelection'
          - type: 'null'
          description: Optional H-managed proxy (e.g. Oxylabs), provisioned for the session. Applied when provisioning a new remote browser session. Only supported for chromium-based browser runners (headful and headless). Ignored when session_id attaches to an existing session. Mutually exclusive with proxy_url.
      type: object
      title: BrowserNetwork
      description: Network egress settings for a remote browser session.
    Skill:
      properties:
        name:
          type: string
          minLength: 1
          title: Name
          description: 'Unique name for this skill in your catalog. Format: lowercase ASCII letters, digits and hyphens; must start and end with alphanumeric; max 63 chars per segment; optional single ''org/'' namespace prefix (e.g. ''h/web-environment'').'
        description:
          type: string
          minLength: 1
          title: Description
          description: When to use this skill. The agent reads this to decide whether to load it.
        body:
          type: string
          minLength: 1
          title: Body
          description: Markdown instructions the agent loads when it uses the skill.
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Optional URL the content was sourced from.
        url_pattern:
          anyOf:
          - type: string
            maxLength: 1024
            minLength: 1
          - type: 'null'
          title: Url Pattern
          description: Optional regex hinting at URLs where this skill applies.
      type: object
      required:
      - name
      - description
      - body
      title: Skill
      description: A named, reusable instruction an agent can draw on during a session.
    CreateSchedule:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        description:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Description
        timing:
          $ref: '#/components/schemas/CronTiming'
        session_request:
          $ref: '#/components/schemas/SessionRequest'
          description: Template used to create each scheduled session; re-resolved on every fire.
      type: object
      required:
      - name
      - timing
      - session_request
      title: CreateSchedule
      description: Register a schedule that creates a session on each fire.
    BrowserTextMode:
      properties:
        type:
          type: string
          const: text
          title: Type
          default: text
        chunk_size:
          type: integer
          exclusiveMinimum: 0.0
          title: Chunk Size
          description: Characters of page text shown per page.
          default: 20000
      type: object
      title: BrowserTextMode
      description: Read-only markdown with URL navigation, no screenshots.
    ManagedProxySelection:
      properties:
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: Two-letter ISO 3166-1 country to source IPs from (e.g. 'US'). Validated server-side.
        sticky:
          type: boolean
          title: Sticky
          description: Keep the same IP across the session where the pool allows it.
          default: true
        pool:
          $ref: '#/components/schemas/ProxyPool'
          description: Which upstream IP pool to draw from.
          default: residential
      type: object
      title: ManagedProxySelection
      description: 'Request for an H-managed proxy, provisioned per session.


        Describes intent only — pool, country, stickiness — never credentials; H resolves

        and injects those when provisioning the session, including which provider backs

        the requested pool.'
    Page_ScheduleRecord_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ScheduleRecord'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
      type: object
      required:
      - items
      - total
      - page
      title: Page[ScheduleRecord]
    ToolDefinition:
      properties:
        name:
          type: string
          maxLength: 64
          minLength: 1
          title: Name
          description: 'Tool name advertised to the model. Format: letters, digits and underscores; must start with a letter or underscore; max 64 chars.'
        description:
          type: string
          minLength: 1
          title: Description
          description: What the tool does, when to use it, and what it returns. Shown to the model verbatim.
        input_schema:
          additionalProperties: true
          type: object
          title: Input Schema
          description: JSON Schema (object type) describing the tool call arguments.
      type: object
      required:
      - name
      - description
      title: ToolDefinition
      description: 'Contract for a tool executed by the API client, not by the agent runtime.


        The agent emits a tool call matching ``input_schema``, pauses, and resumes

        once the client sends back the corresponding tool result.'
    UserMessageEvent:
      properties:
        type:
          type: string
          const: user_message
          title: Type
          default: user_message
        message:
          type: string
          title: Message
          description: Message text sent to the agent.
        images:
          items:
            type: string
          type: array
          title: Images
          description: Optional images attached to the message, as base64 data URIs.
        caller_id:
          type: string
          title: Caller Id
          default: user
      type: object
      required:
      - message
      title: UserMessageEvent
      description: The user is sending a message to an active agent.
    ScheduleRecord:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        timing:
          $ref: '#/components/schemas/CronTiming'
        session_request:
          $ref: '#/components/schemas/SessionRequest'
        paused:
          type: boolean
          title: Paused
        pause_note:
          anyOf:
          - type: string
          - type: 'null'
          title: Pause Note
        next_run_times:
          items:
            type: string
            format: date-time
          type: array
          title: Next Run Times
          description: The next few fire times, empty while paused.
        last_run_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Run At
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - name
      - description
      - timing
      - session_request
      - paused
      - pause_note
      - next_run_times
      - last_run_at
      - created_at
      - updated_at
      title: ScheduleRecord
      description: Schedule as returned by reads.
    PauseSchedule:
      properties:
        note:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Note
      type: object
      title: PauseSchedule
      description: Pause a schedule with an optional note explaining why.
    Browser:
      properties:
        id:
          type: string
          minLength: 1
          title: Id
          description: Catalog identifier for this environment.
        kind:
          type: string
          const: web
          title: Kind
          default: web
        host:
          type: string
          enum:
          - user_device
          - cloud
          title: Host
          description: 'Where the browser runs: ''cloud'' on H Company infrastructure, or ''user_device'' on your own machine.'
          default: cloud
        start_url:
          type: string
          title: Start Url
          description: Initial URL to open.
          default: https://www.bing.com
        headless:
          type: boolean
          title: Headless
          description: Run the browser without a visible window.
          default: false
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
          description: Connect to an existing browser session by id instead of starting a new one.
        mode:
          oneOf:
          - $ref: '#/components/schemas/BrowserVisualMode'
          - $ref: '#/components/schemas/BrowserTextMode'
          title: Mode
          description: How the agent perceives and drives the browser.
          discriminator:
            propertyName: type
            mapping:
              text: '#/components/schemas/BrowserTextMode'
              visual: '#/components/schemas/BrowserVisualMode'
        vault_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Vault Id
          description: Id of a vault config to bind to this browser, letting the agent sign in to sites with secrets resolved from the vault. The vault must belong to the caller's organization. Only supported on cloud-hosted browsers. Omit to run without secret access.
        browser_profile_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Browser Profile Id
          description: Id of a browser profile to load into this browser, restoring saved cookies and storage state from a prior session. The profile must belong to the caller's organization. Only supported on cloud-hosted browsers. Omit to run with a fresh profile.
        use_default_browser_profile:
          type: boolean
          title: Use Default Browser Profile
          description: When true, load the caller's default browser profile for this browser flavor (marked via the browser-profiles API) instead of naming one explicitly. Mutually exclusive with browser_profile_id. When no default exists, an empty profile is auto-created and marked default; default-profile sessions save their final state back on stop when no other session is already persisting the profile. Only supported on cloud-hosted browsers.
          default: false
        persist_browser_profile:
          type: boolean
          title: Persist Browser Profile
          description: When true, the browser profile is updated with this session's final browser state (cookies, storage) when the session ends. Requires browser_profile_id or use_default_browser_profile. Only one active session at a time may persist a given profile; concurrent read-only use is always allowed.
          default: false
        network:
          anyOf:
          - $ref: '#/components/schemas/BrowserNetwork'
          - type: 'null'
          description: Optional network configuration for the remote browser session. Applied only when a new runner session is provisioned (not when session_id is set).
      type: object
      required:
      - id
      title: Browser
      description: A web browser the agent navigates and acts on.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer