openapi: 3.2.0
info:
  title: Capture Sessions Actions API
  version: 6.34.0
  license:
    name: UNLICENSED
    url: https://capture.page
  description: 'OpenAPI contract for Capture browser sessions and Capture actions.


    Session endpoints use Bearer authentication with the same token format as

    Capture MCP:


    `Authorization: Bearer `


    `secret` may be the user''s primary secret or one of their API secrets.'
servers:
- url: https://{host}
  description: Replace `host` with your Capture API deployment hostname.
  variables:
    host:
      default: api.capture.page
security:
- bearerAuth: []
tags:
- name: Actions
  description: Deterministic browser actions executed inside a session.
paths:
  /v1/sessions/{sessionId}/actions:
    post:
      tags:
      - Actions
      operationId: executeAction
      summary: Execute a Capture action
      description: 'Executes a deterministic browser action against the session''s active

        page. If the request lands on a non-owner API instance, Capture routes

        the action to the owning instance through Redis. Responses for existing

        sessions include `expiresInSeconds`, the remaining lifetime at the time

        the action response is sent.'
      parameters:
      - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
            examples:
              goto:
                value:
                  type: goto
                  payload:
                    url: https://example.com
              screenshot:
                value:
                  type: screenshot
                  payload:
                    fullPage: true
              query:
                value:
                  type: query
                  payload:
                    selector: article a[href]
                    fields:
                    - text
                    - href
                    attributes:
                    - href
                    - class
                    - data-tab
                    limit: 400
              content:
                value:
                  type: content
                  payload:
                    format: markdown
      responses:
        '200':
          description: Action result
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/GotoActionResponse'
                - $ref: '#/components/schemas/ScreenshotActionResponse'
                - $ref: '#/components/schemas/GenericActionResponse'
                - $ref: '#/components/schemas/ContentActionResponse'
                - $ref: '#/components/schemas/QueryActionResponse'
        '400':
          description: Invalid action request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Session is unavailable or not active
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ErrorResponse'
                - $ref: '#/components/schemas/InactiveSessionActionResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionErrorResponse'
        '503':
          description: Required backing service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionErrorResponse'
        '504':
          description: Action timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionErrorResponse'
components:
  responses:
    Unauthorized:
      description: Missing or invalid Bearer credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Session not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    BrowserSession:
      type: object
      required:
      - id
      - status
      - startedAt
      - expiresAt
      - billedCredits
      - actionCount
      - actionSuccessCount
      - actionErrorCount
      - actionBreakdown
      - options
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/SessionStatus'
        closeReason:
          type:
          - string
          - 'null'
          example: closed
        createdAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        closedAt:
          type:
          - string
          - 'null'
          format: date-time
        durationSeconds:
          type:
          - integer
          - 'null'
        billedCredits:
          type:
          - integer
          - 'null'
          description: Duration credits charged at 1 credit per elapsed minute, rounded up.
        actionCount:
          type: integer
          description: Number of actions attempted.
        actionSuccessCount:
          type: integer
          description: Number of actions completed successfully.
        actionErrorCount:
          type: integer
          description: Number of actions that failed.
        actionBreakdown:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UsageBreakdownEntry'
        options:
          type: object
          additionalProperties: true
          properties:
            maxTtlSeconds:
              type: integer
            proxy:
              type: boolean
            bypassBotDetection:
              type: boolean
            cdp:
              type: boolean
              description: Whether this session exposes a CDP connection.
        connectUrl:
          type: string
          format: uri
          description: 'Fresh WebSocket URL returned only while a CDP-enabled session is

            active. Client disconnects do not close the Capture session; close

            it with `DELETE /v1/sessions/{sessionId}` when finished.

            '
    SessionStatus:
      type: string
      enum:
      - active
      - closed
      - expired
      - error
    ScreenshotActionResponse:
      allOf:
      - $ref: '#/components/schemas/Success'
      - type: object
        required:
        - contentType
        - bodyBase64
        properties:
          expiresInSeconds:
            type: integer
            minimum: 0
            description: Remaining session lifetime when the action completed.
          contentType:
            type: string
            enum:
            - image/png
          bodyBase64:
            type: string
    GenericActionResponse:
      allOf:
      - $ref: '#/components/schemas/Success'
      - type: object
        additionalProperties: true
        properties:
          expiresInSeconds:
            type: integer
            minimum: 0
            description: Remaining session lifetime when the action completed.
    UsageBreakdownEntry:
      type: object
      required:
      - total
      - success
      - error
      properties:
        total:
          type: integer
        success:
          type: integer
        error:
          type: integer
    InactiveSessionActionResponse:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
      - type: object
        required:
        - session
        properties:
          expiresInSeconds:
            type: integer
            minimum: 0
            description: Remaining session lifetime when the action was rejected.
          session:
            $ref: '#/components/schemas/BrowserSession'
    ContentActionResponse:
      allOf:
      - $ref: '#/components/schemas/Success'
      - type: object
        required:
        - format
        - content
        properties:
          expiresInSeconds:
            type: integer
            minimum: 0
            description: Remaining session lifetime when the action completed.
          format:
            type: string
            enum:
            - text
            - markdown
            - html
            default: text
            description: Requested content format. `text` and `markdown` return cleaned readable content; `html` returns the raw page HTML.
          content:
            type: string
    ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
    GotoActionResponse:
      allOf:
      - $ref: '#/components/schemas/Success'
      - type: object
        required:
        - url
        properties:
          expiresInSeconds:
            type: integer
            minimum: 0
            description: Remaining session lifetime when the action completed.
          matched:
            type: boolean
            description: Whether a selector-based interaction matched an element before executing.
          visible:
            type: boolean
            description: Whether the matched selector element appeared visible before executing.
          elementText:
            type: string
            description: Collapsed text from the matched selector element.
          tagName:
            type: string
            description: Lowercase tag name of the matched selector element.
          attributes:
            type: object
            additionalProperties:
              type: string
            description: Selected attributes from the matched selector element.
          boundingBox:
            type: object
            additionalProperties: true
            description: Bounding box of the matched selector element.
          clickedPoint:
            type: object
            additionalProperties: true
            description: Center point used as a diagnostic for selector click actions.
          hoveredPoint:
            type: object
            additionalProperties: true
            description: Center point used as a diagnostic for selector hover actions.
          url:
            type: string
    Success:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          enum:
          - true
    QueryActionResponse:
      allOf:
      - $ref: '#/components/schemas/Success'
      - type: object
        required:
        - selector
        - fields
        - attributes
        - limit
        - count
        - elements
        properties:
          expiresInSeconds:
            type: integer
            minimum: 0
            description: Remaining session lifetime when the action completed.
          selector:
            type: string
          fields:
            type: array
            items:
              type: string
              enum:
              - text
              - html
              - href
              - src
              - alt
              - title
              - value
              - name
              - id
              - className
              - tag
              - role
              - ariaLabel
              - visible
              - bbox
          attributes:
            type: array
            items:
              type: string
            description: Requested arbitrary DOM attributes returned under each element's nested `attributes` object.
          limit:
            type: integer
            minimum: 1
            maximum: 500
          count:
            type: integer
          elements:
            type: array
            items:
              type: object
              additionalProperties: true
    ActionRequest:
      type: object
      required:
      - type
      additionalProperties: false
      properties:
        type:
          type: string
          enum:
          - goto
          - screenshot
          - wait_for_selector
          - wait_for_timeout
          - click
          - move_mouse
          - drag_mouse
          - hover
          - type
          - type_text
          - fill
          - select
          - check
          - press
          - scroll
          - back
          - forward
          - reload
          - title
          - url
          - cursor_position
          - snapshot
          - console
          - errors
          - content
          - query
          - batch
        payload:
          type: object
          additionalProperties: true
          description: 'Action-specific payload. Supports selectors, coordinates, text,

            keys, navigation options, screenshot options, live viewport options,

            safe DOM query fields, arbitrary query attributes, content format

            (`text`, `markdown`, or `html`; defaults to cleaned text), drag

            paths up to 100 points, and nested batch actions up to 25 actions.

            Prefer `batch` for known multi-step workflows because it executes

            actions sequentially in one session request and reduces repeated

            request, authentication, routing, and network overhead.

            Selector `click` and `hover` responses include matched element

            diagnostics. For `query`, `fields` selects built-in fields,

            `attributes` returns arbitrary DOM attributes under each element''s

            `attributes` object, and `limit` is capped at 500. For `goto`,

            `back`, `forward`, and `reload`, `waitUntil` must be `load`,

            `domcontentloaded`, or `commit`. For `goto`, `screenshot`, and

            action payloads with `screenshot: true`, `viewport`, `vw` / `vh`,

            `scaleFactor` / `deviceScaleFactor`, or `emulateDevice` update the

            live session viewport before the action; this change persists for

            later actions. For `wait_for_timeout`, `timeoutMs` is capped at

            2500.

            '
          properties:
            viewport:
              type: object
              additionalProperties: false
              description: Live viewport to apply before supported actions. Width and height are capped at 5000; device scale factor is capped at 3.
              required:
              - width
              - height
              properties:
                width:
                  type: integer
                  minimum: 1
                  maximum: 5000
                height:
                  type: integer
                  minimum: 1
                  maximum: 5000
                deviceScaleFactor:
                  type: number
                  maximum: 3
                  exclusiveMinimum: 0
            vw:
              type: integer
              minimum: 1
              maximum: 5000
              description: Live viewport width to apply before supported actions. Must be provided with `vh`.
            vh:
              type: integer
              minimum: 1
              maximum: 5000
              description: Live viewport height to apply before supported actions. Must be provided with `vw`.
            scaleFactor:
              type: number
              maximum: 3
              description: Device pixel ratio to apply before supported actions. Alias of `deviceScaleFactor`.
              exclusiveMinimum: 0
            deviceScaleFactor:
              type: number
              maximum: 3
              description: Device pixel ratio to apply before supported actions.
              exclusiveMinimum: 0
            emulateDevice:
              type: string
              description: Device profile key from `/screenshot/devices` to apply before supported actions.
            fields:
              type: array
              items:
                type: string
              description: Built-in fields for `query`. Defaults to `text` when omitted.
            attributes:
              type: array
              items:
                type: string
              description: Arbitrary DOM attributes for `query`, returned under each element's nested `attributes` object.
            limit:
              type: integer
              minimum: 1
              maximum: 500
              description: Maximum number of `query` matches to return. Values above 500 are clamped.
            visibleOnly:
              type: boolean
              description: Only return visible `query` matches when true.
            waitUntil:
              type: string
              enum:
              - load
              - domcontentloaded
              - commit
              default: domcontentloaded
              description: Navigation readiness state for `goto`, `back`, `forward`, and `reload`.
            timeoutMs:
              type: integer
              minimum: 1
              maximum: 2500
              description: Timeout in milliseconds for `wait_for_timeout`. Values above 2500 are clamped.
    ActionErrorResponse:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
      - type: object
        properties:
          expiresInSeconds:
            type: integer
            minimum: 0
            description: Remaining session lifetime when the action was rejected, if the session exists.
          session:
            $ref: '#/components/schemas/BrowserSession'
  parameters:
    SessionId:
      name: sessionId
      in: path
      required: true
      description: Session id returned by `POST /v1/sessions`.
      schema:
        type: string
        example: sess_123e4567-e89b-12d3-a456-426614174000
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: base64(userId:secret)