Airtop Beta API

openapi: 3.2.0
info:
  title: Browser Control Beta API
  version: 1.0.0
servers:
- url: https://api.airtop.ai/api
security:
- BearerAuth: []
tags:
- name: Beta
paths:
  /v1/sessions/{sessionId}/test-cases:
    post:
      description: Creates a challenge test case in Braintrust from session data (stores in page-query-challenge-draft-* or identify-challenge-draft-* datasets)
      operationId: createTestCase
      parameters:
      - description: ID of the session.
        example: 6aac6f73-bd89-4a76-ab32-5a6c422e8b0b
        in: path
        name: sessionId
        required: true
        schema:
          description: ID of the session.
          examples:
          - 6aac6f73-bd89-4a76-ab32-5a6c422e8b0b
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTestCaseBodyV1'
              description: Test case data
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeCreateTestCaseResponseV1EnvelopeDefaultMeta'
                description: Test case creation response
          description: Created
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Error
      summary: Create test case
      tags:
      - Beta
      x-fern-audiences:
      - beta
  /v2/sessions/{sessionId}/model-config-override:
    post:
      description: Override the LLM models used in browser automation for the current session. This endpoint is only available in dev and local environments.
      operationId: ModelConfigOverride
      parameters:
      - description: ID of the session to override model configuration.
        example: 6aac6f73-bd89-4a76-ab32-5a6c422e8b0b
        in: path
        name: sessionId
        required: true
        schema:
          description: ID of the session to override model configuration.
          examples:
          - 6aac6f73-bd89-4a76-ab32-5a6c422e8b0b
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelConfigOverrideRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelConfigOverrideResponseBody'
          description: OK
          headers:
            Meta:
              schema:
                $ref: '#/components/schemas/ExternalSessionAiResponseMetadata'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Error
      security:
      - BearerAuth: []
      summary: Override LLM Model Configuration
      tags:
      - Beta
components:
  schemas:
    CreateTestCaseResponseV1:
      additionalProperties: false
      properties:
        createdAt:
          description: Creation timestamp
          format: date-time
          type: string
        datasetName:
          description: Braintrust dataset name used
          type: string
        status:
          description: Creation status
          enum:
          - created
          type: string
        testCaseId:
          description: Braintrust test case ID
          type: string
      required:
      - testCaseId
      - datasetName
      - status
      - createdAt
      type: object
    EnvelopeDefaultMeta:
      additionalProperties: false
      properties:
        requestId:
          type: string
      type: object
    ScreenshotMetadata:
      additionalProperties: false
      properties:
        dataUrl:
          description: Base64 encoded data URL of screenshot image data
          type: string
        fileId:
          description: Unique identifier for the uploaded file
          type: string
        fileName:
          description: Name of the screenshot file
          type: string
        format:
          description: Format of the screenshot data
          enum:
          - base64
          - url
          type: string
        scrollPosition:
          $ref: '#/components/schemas/ScreenshotScrollPosition'
          description: Scroll position where the screenshot was taken
        signedDownloadUrl:
          description: Signed URL for downloading the screenshot (when format is 'url')
          type: string
        urlExpiry:
          description: Expiration time for the signed URL in ISO format
          type: string
        viewportDimensions:
          $ref: '#/components/schemas/ScreenshotViewportDimensions'
          description: Viewport dimensions of the screenshot
      type: object
    ScreenshotViewportDimensions:
      additionalProperties: false
      properties:
        height:
          description: Height of the viewport in pixels
          format: int64
          type: integer
        width:
          description: Width of the viewport in pixels
          format: int64
          type: integer
      required:
      - width
      - height
      type: object
    Issue:
      additionalProperties: false
      properties:
        code:
          description: Issue code.
          type:
          - string
          - 'null'
        details:
          additionalProperties: {}
          description: Any associated details.
          type:
          - object
          - 'null'
        message:
          description: Message describing the issue.
          type: string
        reason:
          description: Underlying reason for the issue.
          type:
          - string
          - 'null'
        value:
          additionalProperties: {}
          description: Structured payload describing the issue, for issues that carry one.
          type:
          - object
          - 'null'
      required:
      - message
      type: object
    EnvelopeCreateTestCaseResponseV1EnvelopeDefaultMeta:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/CreateTestCaseResponseV1'
        errors:
          items:
            $ref: '#/components/schemas/Issue'
          type:
          - array
          - 'null'
        meta:
          $ref: '#/components/schemas/EnvelopeDefaultMeta'
        warnings:
          items:
            $ref: '#/components/schemas/Issue'
          type:
          - array
          - 'null'
      required:
      - meta
      - data
      - errors
      - warnings
      type: object
    ModelConfigOverrideRequestBody:
      additionalProperties: false
      properties:
        model:
          description: Apply a single model to all automation steps
          type: string
        models:
          additionalProperties:
            type: string
          description: Override specific automation steps with custom models
          type: object
      type: object
    ErrorEnvelope:
      additionalProperties: false
      properties:
        data: {}
        errors:
          items:
            $ref: '#/components/schemas/Issue'
          type:
          - array
          - 'null'
        httpStatus:
          format: int64
          type: integer
        message:
          type: string
        meta: {}
        warnings:
          items:
            $ref: '#/components/schemas/Issue'
          type:
          - array
          - 'null'
      required:
      - httpStatus
      - message
      - meta
      - data
      - errors
      - warnings
      type: object
    TestCaseDataV1:
      additionalProperties: false
      properties:
        expected:
          additionalProperties: {}
          description: Expected output data (flexible structure)
          type: object
        input:
          additionalProperties: {}
          description: Test input data (flexible structure)
          type: object
        metadata:
          additionalProperties: {}
          description: Test metadata (flexible structure)
          type: object
      required:
      - input
      - expected
      - metadata
      type: object
    ExternalSessionAiResponseMetadataUsage:
      additionalProperties: false
      properties:
        credits:
          description: The credit usage for this request
          format: int64
          type: integer
        id:
          description: The id of the request
          type: string
      required:
      - id
      - credits
      type: object
    CreateTestCaseBodyV1:
      additionalProperties: false
      properties:
        testCase:
          $ref: '#/components/schemas/TestCaseDataV1'
          description: Test case data structure
        testType:
          description: Type of test case
          enum:
          - PageQuery
          - ClickMicroInteraction
          - TypeMicroInteraction
          - FormFilling
          type: string
      required:
      - testType
      - testCase
      type: object
    ClientProvidedResponseMetadata:
      additionalProperties: false
      properties:
        clientRequestId:
          type: string
      type: object
    ExternalSessionAiResponseMetadata:
      additionalProperties: false
      properties:
        actionId:
          description: The id of the action that was performed.
          type: string
        cacheHit:
          description: Whether a cached strategy was used for this operation.
          type: boolean
        clientProvided:
          $ref: '#/components/schemas/ClientProvidedResponseMetadata'
        effort:
          description: The effort level used for this operation.
          enum:
          - low
          - high
          type: string
        requestId:
          type: string
        screenshots:
          description: Array containing any requested screenshots from the operation.
          items:
            $ref: '#/components/schemas/ScreenshotMetadata'
          type:
          - array
          - 'null'
        status:
          description: Outcome of the operation.
          enum:
          - success
          - partial
          - failure
          type: string
        usage:
          $ref: '#/components/schemas/ExternalSessionAiResponseMetadataUsage'
      required:
      - status
      - usage
      type: object
    ModelConfigOverrideResponseBody:
      additionalProperties: false
      properties:
        success:
          type: boolean
      required:
      - success
      type: object
    ScreenshotScrollPosition:
      additionalProperties: false
      properties:
        left:
          description: Horizontal scroll position in pixels
          format: int64
          type: integer
        top:
          description: Vertical scroll position in pixels
          format: int64
          type: integer
      required:
      - top
      - left
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http
      x-fern-bearer:
        name: apiKey
x-provenance:
  method: harvested
  publisher: Airtop
  source: https://api.airtop.ai/api/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)