Anchor Browser Browser Sessions API

openapi: 3.2.0
info:
  title: AnchorBrowser Agentic capabilities Browser Sessions API
  version: 1.0.0
  description: APIs to manage all browser-related actions and configuration.
servers:
- url: https://api.anchorbrowser.io
  description: API server
tags:
- name: Browser Sessions
paths:
  /v1/sessions:
    get:
      summary: List Sessions History Page
      description: 'Retrieves a paginated list of sessions for the authenticated team with support for

        sorting and advanced filtering. This endpoint mirrors the backend session history-page

        filtering behavior.

        '
      security:
      - api_key_header: []
      tags:
      - Browser Sessions
      parameters:
      - in: query
        name: page
        required: false
        description: Page number to fetch.
        schema:
          type: integer
          minimum: 1
          default: 1
      - in: query
        name: limit
        required: false
        description: Number of sessions per page. Supported values are 10, 20, and 50.
        schema:
          type: integer
          enum:
          - 10
          - 20
          - 50
          default: 10
      - in: query
        name: sort_by
        required: false
        description: 'Sort field. Common values are `created_at`, `session_id`, `used_credits`,

          `created_at`, and `api_key_name`.

          '
        schema:
          type: string
          default: created_at
      - in: query
        name: sort_order
        required: false
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - in: query
        name: search
        required: false
        description: Comma-separated tag search terms (partial, case-insensitive).
        schema:
          type: string
      - in: query
        name: status
        required: false
        description: Exact session status filter.
        schema:
          type: string
      - in: query
        name: tags
        required: false
        description: Comma-separated tag list. Session must include all provided tags.
        schema:
          type: string
        example: production,scraping
      - in: query
        name: domains
        required: false
        description: Comma-separated domain list. Session must include all provided domains.
        schema:
          type: string
        example: example.com,anchorbrowser.io
      - in: query
        name: created_from
        required: false
        description: Include sessions created at or after this timestamp (ISO 8601).
        schema:
          type: string
          format: date-time
      - in: query
        name: created_to
        required: false
        description: Include sessions created at or before this timestamp (ISO 8601).
        schema:
          type: string
          format: date-time
      - in: query
        name: batch_id
        required: false
        description: Filter by batch identifier.
        schema:
          type: string
      - in: query
        name: task_initiated
        required: false
        description: Filter by whether the session was task-initiated.
        schema:
          type: boolean
      - in: query
        name: playground
        required: false
        description: Filter by whether the session is a playground session.
        schema:
          type: boolean
      - in: query
        name: proxy
        required: false
        description: Filter by whether proxy was active for the session.
        schema:
          type: boolean
      - in: query
        name: extra_stealth
        required: false
        description: Filter by whether extra stealth mode was active.
        schema:
          type: boolean
      - in: query
        name: profile_name
        required: false
        description: Case-insensitive partial match on browser profile name.
        schema:
          type: string
        example: Default profile
      responses:
        '200':
          description: Paginated sessions history retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionHistoryPageResponse'
              examples:
                filteredSessionsPage:
                  summary: Example filtered session page
                  value:
                    data:
                      sessions:
                      - id: sess_123456
                        status: completed
                        tags:
                        - production
                        - scraping
                        headless: false
                        recording: true
                        used_credits: 12.5
                        proxy_bytes: 102400
                        proxy_type: anchor_proxy
                        steps: 48
                        duration: 420
                        created_at: '2026-03-09T12:34:56.789Z'
                        user_configuration:
                          session:
                            idle_timeout: 300
                        task_initiated: true
                        task_executions_count: 2
                        api_key_name: automation-key
                        browser_ip: 192.0.2.10
                        domains:
                        - example.com
                      total: 145
                      page: 1
                      total_pages: 15
        '400':
          description: Invalid query parameters (for example unsupported limit or sort options).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Start Browser Session
      description: Allocates a new browser session for the user, with optional configurations for ad-blocking, captcha solving, proxy usage, and idle timeout.
      security:
      - api_key_header: []
      tags:
      - Browser Sessions
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreateRequestSchema'
      responses:
        '200':
          description: Successfully returned a browser object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionCreateResponseSchema'
        '400':
          description: Bad Request - Invalid request parameters or configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                captchaSolverRequiresProxy:
                  summary: CAPTCHA solver requires proxy to be active.
                  value:
                    error:
                      code: 400
                      message: CAPTCHA solver requires proxy to be active.
        '402':
          description: Payment Required - Insufficient credits to allocate a new browser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests — session creation rate limit exceeded.
          headers:
            RateLimit:
              description: 'IETF draft-8 Rate-limit headers.

                '
              schema:
                type: string
              example: '"5-in-1min"; r=0; t=58'
            RateLimit-Policy:
              schema:
                type: string
              example: '"5-in-1min"; q=5; w=60; pk=:ZGQ0YzBjYzVhZjQ1:'
            Retry-After:
              description: Seconds until the rate-limit window resets (matches the `t` parameter in `RateLimit` when the limit is exceeded).
              schema:
                type: integer
              example: 58
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionCreationRateLimited:
                  summary: Session creation rate limit exceeded
                  value:
                    error:
                      code: 429
                      message: Session creation rate limit exceeded.
  /v1/sessions/async:
    post:
      summary: Start Browser Session (async)
      description: 'Non-blocking variant of `POST /v1/sessions`. Returns a `request_id`

        immediately and provisions the underlying browser pod in the

        background. Poll `GET /v1/sessions/async/{request_id}/status` until

        `status` becomes `ready` to obtain the resolved `session_id`,

        `cdp_url` and `live_view_url`.

        '
      security:
      - api_key_header: []
      tags:
      - Browser Sessions
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreateRequestSchema'
      responses:
        '200':
          description: Async session creation accepted; poll the status endpoint to resolve.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncSessionCreateResponseSchema'
        '400':
          description: Invalid request parameters or configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - Insufficient credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Project cost limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: API key would exceed batch browser limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/sessions/async/{request_id}/status:
    get:
      summary: Async Session Status
      description: 'Polling endpoint paired with `POST /v1/sessions/async`. Returns the

        current lifecycle `status` of the async request and, once the pod is

        up, the embedded `session` object containing `session_id`, `cdp_url`

        and `live_view_url`.

        '
      security:
      - api_key_header: []
      tags:
      - Browser Sessions
      parameters:
      - name: request_id
        in: path
        required: true
        description: The `request_id` returned from `POST /v1/sessions/async`.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Async session status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncSessionStatusResponseSchema'
        '401':
          description: Invalid API Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Async request not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/sessions/all:
    delete:
      summary: End All Sessions
      description: Terminates all active browser sessions associated with the provided API key.
      tags:
      - Browser Sessions
      security:
      - api_key_header: []
      responses:
        '200':
          description: Successfully terminated all active browser sessions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  /v1/sessions/all/status:
    get:
      summary: List All Sessions Status
      description: Retrieves status information for all browser sessions associated with the API key.
      security:
      - api_key_header: []
      tags:
      - Browser Sessions
      parameters:
      - in: query
        name: tags
        required: false
        description: Comma-separated list of session tags to filter by. Sessions must contain all provided tags.
        schema:
          type: string
        example: production,scraping
      - in: query
        name: domains
        required: false
        description: Comma-separated list of domains to filter by. Sessions must contain all provided domains.
        schema:
          type: string
        example: example.com,anchorbrowser.io
      - in: query
        name: created_from
        required: false
        description: Include sessions created at or after this timestamp (ISO 8601).
        schema:
          type: string
          format: date-time
      - in: query
        name: created_to
        required: false
        description: Include sessions created at or before this timestamp (ISO 8601).
        schema:
          type: string
          format: date-time
      - in: query
        name: batch_id
        required: false
        description: Filter sessions by batch identifier.
        schema:
          type: string
      - in: query
        name: task_initiated
        required: false
        description: Filter by whether the session was initiated by a task.
        schema:
          type: boolean
      - in: query
        name: playground
        required: false
        description: Filter by whether the session is a playground session.
        schema:
          type: boolean
      - in: query
        name: proxy
        required: false
        description: Filter by whether proxy was active for the session.
        schema:
          type: boolean
      - in: query
        name: extra_stealth
        required: false
        description: Filter by whether extra stealth mode was active for the session.
        schema:
          type: boolean
      - in: query
        name: profile_name
        required: false
        description: Filter sessions by browser profile name (case-insensitive partial match).
        schema:
          type: string
        example: Default profile
      responses:
        '200':
          description: Successfully retrieved status for all browser sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListResponse'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/sessions/history:
    get:
      summary: Get Sessions History
      description: Retrieves session usage analytics for the authenticated team.
      security:
      - api_key_header: []
      tags:
      - Browser Sessions
      parameters:
      - in: query
        name: from_date
        required: false
        description: Start date for filtering (ISO 8601 format).
        schema:
          type: string
          format: date-time
      - in: query
        name: to_date
        required: false
        description: End date for filtering (ISO 8601 format).
        schema:
          type: string
          format: date-time
      - in: query
        name: granularity
        required: false
        description: Time granularity for aggregation.
        schema:
          type: string
          enum:
          - hour
          - day
          - week
          - month
          default: day
      - in: query
        name: metrics
        required: false
        description: Metrics to include in the response.
        schema:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
              enum:
              - session_count
              - proxy_bytes
              - ai_steps
              - session_hours
              - credits_used
              - screenshots
              - network_bytes_total
          default:
          - session_count
      - in: query
        name: page
        required: false
        description: Page number for pagination.
        schema:
          type: integer
          minimum: 1
          default: 1
      - in: query
        name: limit
        required: false
        description: Number of records per page.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      responses:
        '200':
          description: Session history analytics retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionHistoryResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/sessions/{session_id}:
    get:
      summary: Get Browser Session
      description: Retrieves detailed information about a specific browser session.
      tags:
      - Browser Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        description: The ID of the session to retrieve.
        schema:
          type: string
      security:
      - api_key_header: []
      responses:
        '200':
          description: Session retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: The session data.
                    properties:
                      session_id:
                        type: string
                        description: The unique identifier of the session.
                      team_id:
                        type: string
                        description: The team ID associated with the session.
                      duration:
                        type: integer
                        description: The duration of the session in seconds.
                      status:
                        type: string
                        description: The current status of the session.
                      credits_used:
                        type: number
                        description: The number of credits consumed by the session.
                      configuration:
                        type: object
                        description: The configuration settings for the session.
                      playground:
                        type: boolean
                        description: Whether this is a playground session.
                      proxy_bytes:
                        type: integer
                        description: The number of bytes transferred through the proxy.
                      tokens:
                        type: object
                        description: Token usage information.
                      steps:
                        type: integer
                        description: Number of AI agent steps executed in the session.
                      tags:
                        type: object
                        description: Tags associated with the session.
                      created_at:
                        type: string
                        format: date-time
                        description: The timestamp when the session was created.
        '404':
          description: Session not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Failed to fetch session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: End Browser Session
      description: Deletes the browser session associated with the provided browser session ID. Requires a valid API key for authentication.
      tags:
      - Browser Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        description: The ID of the browser session to end.
        schema:
          type: string
      security:
      - api_key_header: []
      responses:
        '200':
          description: Browser session ended successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Invalid API Key or browser session ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/sessions/{session_id}/pages:
    get:
      summary: Get Browser Session Pages
      description: Retrieves a list of pages associated with a specific browser session.
      tags:
      - Browser Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        description: The ID of the session to retrieve pages for.
        schema:
          type: string
      security:
      - api_key_header: []
      responses:
        '200':
          description: Session pages retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The unique identifier of the page.
                    title:
                      type: string
                      description: The title of the page.
                    url:
                      type: string
                      description: The URL of the page.
                    frontend_url:
                      type: string
                      description: The frontend URL for accessing the page.
                  required:
                  - id
                  - title
                  - url
                  - frontend_url
        '401':
          description: Invalid API Key or unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/sessions/{sessionId}/uploads:
    post:
      summary: Upload Files
      description: 'Upload files directly to a browser session for use with web forms and file inputs.


        Files are saved to the session''s uploads directory and can be referenced in CDP commands.

        '
      security:
      - api_key_header: []
      tags:
      - Browser Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        description: The browser session ID
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: File to upload to the browser session
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                      message:
                        type: string
        '400':
          description: Invalid request (no file uploaded or file too large)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Failed to upload file
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/ErrorResponse'
  /v1/sessions/{session_id}/downloads:
    get:
      summary: List Session Downloads
      description: Retrieves metadata of files downloaded during a browser session. Requires a valid API key for authentication.
      tags:
      - Browser Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        description: The unique identifier of the browser session to retrieve downloads for.
        schema:
          type: string
      security:
      - api_key_header: []
      responses:
        '200':
          description: A list of download metadata associated with the browser session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadListResponse'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The browser session or its downloads metadata could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests, please try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    OnePasswordConfig:
      oneOf:
      - $ref: '#/components/schemas/OnePasswordAllSecretsConfig'
      - $ref: '#/components/schemas/OnePasswordSpecificSecretsConfig'
    OnePasswordAllSecretsConfig:
      type: object
      required:
      - load_mode
      properties:
        load_mode:
          type: string
          enum:
          - all
          description: Load all secrets from 1Password
    AsyncSessionStatusResponseSchema:
      type: object
      description: 'Polling response for `GET /v1/sessions/async/{request_id}/status`.

        '
      properties:
        data:
          type: object
          required:
          - request_id
          - status
          - created_at
          - progress
          properties:
            request_id:
              type: string
              format: uuid
              description: The `request_id` returned from `POST /v1/sessions/async`.
            status:
              type: string
              enum:
              - pending
              - processing
              - ready
              - completed
              - failed
              - cancelled
              description: 'Lifecycle of the async request itself. `ready` is surfaced once

                the underlying browser pod is up and the session is connectable.

                '
            created_at:
              type: string
              format: date-time
              description: When the async request was accepted.
            session:
              $ref: '#/components/schemas/BatchSessionItemSchema'
              description: 'The single browser session backing this async request.

                Absent until the underlying pod registers and the session row

                is inserted.

                '
            progress:
              type: object
              required:
              - current_phase
              properties:
                current_phase:
                  type: string
                  enum:
                  - queued
                  - provisioning
                  - configuring
                  - ready
                  description: The session's current pod-provisioning phase.
    SessionStatus:
      type: object
      properties:
        session_id:
          type: string
          description: Unique identifier for the browser session
        status:
          type: string
          description: Current status of the browser session
        tags:
          type: array
          items:
            type: string
          description: Custom labels assigned to this browser session
        created_at:
          type: string
          format: date-time
          description: Timestamp when the browser session was created
      required:
      - session_id
      - status
      - created_at
    BrowserConfig:
      type: object
      description: Browser-specific configurations.
      properties:
        profile:
          type: object
          description: Options for managing and persisting browser session profiles.
          properties:
            name:
              type: string
              description: The name of the profile to be used during the browser session.
            persist:
              type: boolean
              description: Indicates whether the browser session profile data should be saved when the browser session ends. Defaults to `false`.
        adblock:
          type: object
          description: Configuration for ad-blocking.
          properties:
            active:
              type: boolean
              description: Enable or disable ad-blocking. Defaults to `true`.
        popup_blocker:
          type: object
          description: Configuration for popup blocking.
          properties:
            active:
              type: boolean
              description: Blocks popups, including ads and CAPTCHA consent banners. Requires adblock to be active. Defaults to `true`.
        captcha_solver:
          type: object
          description: Configuration for captcha-solving.
          properties:
            active:
              type: boolean
              description: Enable or disable captcha-solving. Requires proxy to be active. Defaults to `false`.
        headless:
          type: object
          description: Configuration for headless mode.
          properties:
            active:
              type: boolean
              description: Whether browser should be headless or headful. Defaults to `false`.
        viewport:
          type: object
          description: Configuration for the browser's viewport size.
          properties:
            width:
              type: integer
              description: Width of the viewport in pixels. Defaults to `1440`.
            height:
              type: integer
              description: Height of the viewport in pixels. Defaults to `900`.
        fullscreen:
          type: object
          description: Configuration for fullscreen mode.
          properties:
            active:
              type: boolean
              description: Enable or disable fullscreen mode. When enabled, the browser will start in fullscreen mode. Defaults to `false`.
        pdf_viewer:
          type: object
          description: Configuration for PDF viewer mode.
          properties:
            active:
  

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/anchorbrowser/refs/heads/main/openapi/anchorbrowser-browser-sessions-api-openapi.yml