> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infrawatch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Queue a browser session.

> Validates the request and atomically admits it against caller and
organisation concurrency limits before returning. Platform Core does
not contact browser infrastructure in this request; a durable dispatcher
provisions valid queued sessions asynchronously.

Reusing an Idempotency-Key with the same normalized request returns the
existing resource. Reusing it with a different request returns 409.




## OpenAPI

````yaml https://api.infrawatch.com/openapi.json?contract=d15375c post /projects/{project_uuid}/sessions
openapi: 3.1.0
info:
  description: >-
    Customer-facing Infrawatch APIs. Authenticate with an API key unless an
    operation documents another supported credential.


    ### Infrawatch Public API


    Public API authenticated exclusively with Infrawatch API keys.


    ### Infrawatch Customer Alerting API


    Project alert rules, destinations, silences, inbox state, and delivery
    history.


    ### Infrawatch Remote Browser API


    Project-scoped interactive browser sessions owned by Platform Core.


    Session admission, lifecycle, RBAC, audit, usage, screenshot history, and

    stream tickets are Platform Core resources. The browser master is private

    infrastructure and its identifiers, proxy routes, process options, and

    credentials are never exposed by this API.


    A session and all of its evidence are private to the credential that created

    it. Project managers may list project session metadata, inspect one
    session's

    metadata, and terminate it, but cannot access its live stream, screenshots,

    or network events.


    Terminal session metadata and screenshots are retained indefinitely. A

    creator can replay a terminal session as a new queued resource while

    preserving a durable link to the source session.


    ### Infrawatch ESI API


    Customer-facing External Surface Intelligence API for project-scoped

    product data authenticated by an Infrawatch API key. API keys

    are constrained to their immutable owner's project ceiling and assigned

    ESI scopes; human project-manager fallback never expands an API key.

    Authorised API-key requests are rate-limited and consume monthly quota.


    ### Infrawatch Reports API


    Threat report discovery API authenticated by an Infrawatch API key.


    ### Infrawatch Public Rules API


    Account-aware rule authoring, taxonomy, catalogue, and runtime observations
    for API clients.


    ### Infrawatch Search API


    Search hosts, services, DNS records, and certificates. Complete
    percent-encoded query strings are limited to 65536 bytes.
  title: Infrawatch Customer API
  version: 1.0.0
servers:
  - description: Infrawatch customer API
    url: https://api.infrawatch.com/api/v1
security: []
tags:
  - name: API Usage
  - name: Projects
  - name: Alert destinations
  - name: Alert rules
  - name: Alert silences
  - name: Alerts
  - name: Browser sessions
  - name: Browser evidence
  - name: Browser streaming
  - name: Access
  - name: Inventory
  - name: Dangling DNS
  - name: Findings
  - name: Secrets
  - name: Typosquatting
  - name: Services
  - name: AI Surface
  - description: Search hosts, services, DNS records, certificates, and open directories.
    name: Search
  - name: Dashboard
  - name: Reports
  - name: Rules
  - name: Rule tags
  - name: Rule observations
paths:
  /projects/{project_uuid}/sessions:
    servers:
      - url: https://api.infrawatch.com/api/v1
    post:
      tags:
        - Browser sessions
      summary: Queue a browser session.
      description: |
        Validates the request and atomically admits it against caller and
        organisation concurrency limits before returning. Platform Core does
        not contact browser infrastructure in this request; a durable dispatcher
        provisions valid queued sessions asynchronously.

        Reusing an Idempotency-Key with the same normalized request returns the
        existing resource. Reusing it with a different request returns 409.
      operationId: createBrowserSession
      parameters:
        - $ref: '#/components/parameters/browser_v1_ProjectUUID'
        - $ref: '#/components/parameters/browser_v1_IdempotencyKey'
      requestBody:
        content:
          application/json:
            examples:
              publicWebsite:
                value:
                  browser_profile: windows
                  egress_country: GB
                  start_url: https://example.com/
                  viewport:
                    height: 900
                    width: 1440
            schema:
              $ref: '#/components/schemas/browser_v1_CreateSessionRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  session:
                    $ref: '#/components/schemas/browser_v1_Session'
                required:
                  - session
                type: object
          description: Session accepted or an identical idempotent resource returned.
          headers:
            Location:
              description: Project-scoped URL of the durable session resource.
              required: true
              schema:
                type: string
        '400':
          $ref: '#/components/responses/browser_v1_BadRequest'
        '401':
          $ref: '#/components/responses/browser_v1_Unauthorized'
        '403':
          $ref: '#/components/responses/browser_v1_Forbidden'
        '404':
          $ref: '#/components/responses/browser_v1_NotFound'
        '409':
          $ref: '#/components/responses/browser_v1_Conflict'
        '429':
          $ref: '#/components/responses/browser_v1_TooManyRequests'
        '503':
          $ref: '#/components/responses/browser_v1_Unavailable'
      security:
        - apiKeyAuth: []
      x-codeSamples:
        - label: API key
          lang: Shell
          source: |
            curl --request POST \
              --url https://api.infrawatch.com/api/v1/projects/PROJECT_UUID/sessions \
              --header 'X-API-Key: <your-api-key>' \
              --header 'Idempotency-Key: customer-job-123' \
              --header 'Content-Type: application/json' \
              --data '{"start_url":"https://example.com","browser_profile":"windows","egress_country":"GB","viewport":{"width":1440,"height":900}}'
components:
  parameters:
    browser_v1_ProjectUUID:
      in: path
      name: project_uuid
      required: true
      schema:
        format: uuid
        type: string
    browser_v1_IdempotencyKey:
      in: header
      name: Idempotency-Key
      required: true
      schema:
        maxLength: 200
        minLength: 1
        type: string
  schemas:
    browser_v1_CreateSessionRequest:
      additionalProperties: false
      properties:
        browser_profile:
          allOf:
            - $ref: '#/components/schemas/browser_v1_BrowserProfile'
          default: windows
        egress_country:
          description: ISO 3166-1 alpha-2 country returned by capabilities.
          pattern: ^[A-Z]{2}$
          type: string
        start_url:
          description: >-
            Public HTTP or HTTPS URL. Credentials and private, loopback,
            link-local, metadata, localhost, and local-network targets are
            rejected.
          format: uri
          maxLength: 2048
          type: string
        viewport:
          allOf:
            - $ref: '#/components/schemas/browser_v1_Viewport'
          default:
            height: 900
            width: 1440
      required:
        - start_url
        - egress_country
      type: object
    browser_v1_Session:
      properties:
        browser_profile:
          $ref: '#/components/schemas/browser_v1_BrowserProfile'
        close_requested_at:
          format: date-time
          type: string
        created_at:
          format: date-time
          type: string
        creator:
          $ref: '#/components/schemas/browser_v1_Creator'
        egress_country:
          pattern: ^[A-Z]{2}$
          type: string
        expires_at:
          description: |
            When a live session ends unless something touches it first:
            the earlier of its idle window lapsing and its hard lifetime.
            Absent once the session is terminal.
          format: date-time
          type: string
        failure_code:
          enum:
            - creation_timeout
            - dispatch_interrupted
            - creation_failed
          type: string
        last_activity_at:
          format: date-time
          type: string
        project_uuid:
          format: uuid
          type: string
        ready_at:
          format: date-time
          type: string
        replayed_from_session_uuid:
          format: uuid
          type: string
        start_url:
          format: uri
          type: string
        state:
          $ref: '#/components/schemas/browser_v1_SessionState'
        terminal_at:
          format: date-time
          type: string
        updated_at:
          format: date-time
          type: string
        uuid:
          format: uuid
          type: string
        viewport:
          $ref: '#/components/schemas/browser_v1_Viewport'
      required:
        - uuid
        - project_uuid
        - creator
        - start_url
        - browser_profile
        - egress_country
        - viewport
        - state
        - last_activity_at
        - created_at
        - updated_at
      type: object
    browser_v1_BrowserProfile:
      description: Browser identity profile; not the private worker operating system.
      enum:
        - windows
        - macos
        - linux
      type: string
    browser_v1_Viewport:
      properties:
        height:
          maximum: 1600
          minimum: 480
          type: integer
        width:
          maximum: 2560
          minimum: 640
          type: integer
      required:
        - width
        - height
      type: object
    browser_v1_Creator:
      properties:
        kind:
          enum:
            - membership
            - api_key
          type: string
        uuid:
          format: uuid
          type: string
      required:
        - kind
        - uuid
      type: object
    browser_v1_SessionState:
      enum:
        - queued
        - starting
        - ready
        - closing
        - closed
        - failed
        - expired
      type: string
    browser_v1_APIError:
      properties:
        error:
          properties:
            code:
              type: string
            field_errors:
              items:
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - field
                  - code
                  - message
                type: object
              type: array
            message:
              type: string
            request_id:
              type: string
          required:
            - code
            - message
          type: object
      required:
        - error
      type: object
  responses:
    browser_v1_BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/browser_v1_APIError'
      description: >-
        Invalid browser request, URL, profile, country, viewport, cursor, or
        identifier.
    browser_v1_Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/browser_v1_APIError'
      description: Authentication or stream ticket required.
    browser_v1_Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/browser_v1_APIError'
      description: Permission, project access, entitlement, or stream origin denied.
    browser_v1_NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/browser_v1_APIError'
      description: >-
        Project, session, or screenshot not found or not visible to this
        credential.
    browser_v1_Conflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/browser_v1_APIError'
      description: Idempotency conflict or an existing stream controller.
    browser_v1_TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/browser_v1_APIError'
      description: >-
        Caller or organisation active-session limit reached, or the API
        credential exceeded its operational rate limit.
      headers:
        Retry-After:
          schema:
            minimum: 0
            type: integer
    browser_v1_Unavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/browser_v1_APIError'
      description: Browser, egress, Redis, or screenshot storage dependency is unavailable.
  securitySchemes:
    apiKeyAuth:
      description: >-
        Infrawatch API key. Supply the complete key directly as the header
        value.
      in: header
      name: X-API-Key
      type: apiKey

````