openapi: 3.2.0
info:
  title: Capture Sessions 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: Sessions
  description: Stateful cloud browser sessions.
paths:
  /v1/sessions:
    post:
      tags:
      - Sessions
      operationId: createSession
      summary: Create a browser session
      description: 'Creates a stateful browser session on the handling Capture API instance.

        The session is automatically closed when its TTL expires. Billable

        sessions charge 1 credit per elapsed minute, rounded up. Each user

        can have up to 5 active sessions at a time.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
            examples:
              defaultTtl:
                value: {}
              customTtl:
                value:
                  maxTtlSeconds: 300
              cdp:
                value:
                  maxTtlSeconds: 300
                  cdp: true
              proxyAndBypass:
                value:
                  maxTtlSeconds: 300
                  proxy: true
                  bypassBotDetection: true
              cdpWithProxy:
                summary: CDP session through the configured proxy
                value:
                  maxTtlSeconds: 300
                  cdp: true
                  proxy: true
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSessionResponse'
              examples:
                default:
                  value:
                    success: true
                    session:
                      id: sess_123e4567-e89b-12d3-a456-426614174000
                      status: active
                      expiresAt: '2026-06-17T11:20:00.000Z'
                      maxTtlSeconds: 300
                      proxy: false
                      bypassBotDetection: false
                      cdp: false
                cdp:
                  value:
                    success: true
                    session:
                      id: sess_123e4567-e89b-12d3-a456-426614174000
                      status: active
                      expiresAt: '2026-06-17T11:20:00.000Z'
                      maxTtlSeconds: 300
                      proxy: false
                      bypassBotDetection: false
                      cdp: true
                      connectUrl: wss://connect.capture.page/cdp?token=v1.example
                cdpWithProxy:
                  value:
                    success: true
                    session:
                      id: sess_123e4567-e89b-12d3-a456-426614174000
                      status: active
                      expiresAt: '2026-06-17T11:20:00.000Z'
                      maxTtlSeconds: 300
                      proxy: true
                      bypassBotDetection: false
                      cdp: true
                      connectUrl: wss://connect.capture.page/cdp?token=v1.example
        '400':
          description: Invalid session options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                cdpWithBypass:
                  summary: CDP cannot be combined with bypassBotDetection
                  value:
                    success: false
                    error: cdp cannot be combined with bypassBotDetection
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          description: User has reached the active session limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionLimitErrorResponse'
        '503':
          description: CDP session creation is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: CDP connections are not available
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/sessions/{sessionId}:
    get:
      tags:
      - Sessions
      operationId: getSession
      summary: Get session metadata
      parameters:
      - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Session metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSessionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
      - Sessions
      operationId: closeSession
      summary: Close a browser session
      description: 'Closes an active session and charges duration credits once. Repeated

        close requests for an already-finalized session are idempotent.'
      parameters:
      - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Session closed or already finalized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSessionResponse'
        '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':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
components:
  responses:
    GatewayTimeout:
      description: Action timed out
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
    Forbidden:
      description: User is not allowed to create the session
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: Required backing service is unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CreateSessionRequest:
      type: object
      additionalProperties: false
      properties:
        maxTtlSeconds:
          type: integer
          minimum: 1
          maximum: 900
          description: Maximum session lifetime. Values above 900 are capped.
          example: 300
        proxy:
          type: boolean
          default: false
          description: Use the authenticated user's configured browser proxy.
        bypassBotDetection:
          type: boolean
          default: false
          description: Use Capture's configured captcha/bot-detection bypass browser when available.
        cdp:
          type: boolean
          default: false
          description: 'Expose a Chrome DevTools Protocol connection URL for direct browser

            automation clients. CDP sessions can be combined with `proxy` so CDP-created

            targets use the authenticated user''s configured proxy, but cannot be combined

            with `bypassBotDetection`. CDP connection support must be available.

            The create response includes `session.cdp`; session metadata includes

            `session.options.cdp`.

            '
    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
    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'
    CreateSessionResponse:
      allOf:
      - $ref: '#/components/schemas/Success'
      - type: object
        required:
        - session
        properties:
          session:
            type: object
            required:
            - id
            - status
            - expiresAt
            - maxTtlSeconds
            - proxy
            - bypassBotDetection
            - cdp
            properties:
              id:
                type: string
              status:
                $ref: '#/components/schemas/SessionStatus'
              expiresAt:
                type: string
                format: date-time
              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 for active CDP-enabled sessions. Use

                  this with clients such as Puppeteer `connect` or Playwright

                  `connectOverCDP`.

                  '
    ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
    SessionLimitErrorResponse:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
      - type: object
        required:
        - activeSessionCount
        - maxConcurrentSessions
        properties:
          activeSessionCount:
            type: integer
            example: 5
          maxConcurrentSessions:
            type: integer
            example: 5
    Success:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          enum:
          - true
    GetSessionResponse:
      allOf:
      - $ref: '#/components/schemas/Success'
      - type: object
        required:
        - session
        properties:
          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)