openapi: 3.0.1
info:
  title: Airtop AI Query Sessions API
  description: REST API for Airtop, a cloud-browser platform for AI agents. Create and manage remote Chromium browser sessions, open and navigate windows, drive pages with natural-language interactions (click, type, hover, scroll), query and extract page content with AI, capture screenshots, and persist state with profiles. All requests are authenticated with a Bearer API key.
  termsOfService: https://www.airtop.ai/legal/terms-of-service
  contact:
    name: Airtop Support
    url: https://docs.airtop.ai
  version: '1.0'
servers:
- url: https://api.airtop.ai/api/v1
  description: Airtop production API
security:
- bearerAuth: []
tags:
- name: Sessions
  description: Create and manage cloud browser sessions.
paths:
  /sessions:
    get:
      operationId: listSessions
      tags:
      - Sessions
      summary: List sessions
      description: Returns the cloud browser sessions for the authenticated account.
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A list of sessions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionsListResponse'
    post:
      operationId: createSession
      tags:
      - Sessions
      summary: Create session
      description: Starts a new cloud browser session (a remote Chromium instance) with optional profile, proxy, recording, captcha solving, and idle timeout configuration. Returns connection URLs (CDP and WebDriver) for the live session.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionConfig'
      responses:
        '200':
          description: The created session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
  /sessions/{sessionId}:
    get:
      operationId: getSession
      tags:
      - Sessions
      summary: Get session info
      description: Returns details and status for a single session.
      parameters:
      - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: The session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
    delete:
      operationId: terminateSession
      tags:
      - Sessions
      summary: Terminate session
      description: Ends a session and releases its cloud browser resources.
      parameters:
      - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Session terminated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeResponse'
  /requests/{requestId}:
    get:
      operationId: getRequestStatus
      tags:
      - Sessions
      summary: Get request status
      description: Returns the status and result of an asynchronous request previously issued against the API.
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeResponse'
components:
  parameters:
    SessionId:
      name: sessionId
      in: path
      required: true
      description: Identifier of the cloud browser session.
      schema:
        type: string
  schemas:
    SessionResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Session'
    SessionConfig:
      type: object
      properties:
        configuration:
          type: object
          properties:
            profileName:
              type: string
              description: Name of a profile to load into the session.
            extensionIds:
              type: array
              items:
                type: string
              description: Chrome Web Store extension IDs to load.
            proxy:
              description: Proxy configuration (boolean, object, or array).
              oneOf:
              - type: boolean
              - type: object
              - type: array
                items:
                  type: object
            record:
              type: boolean
              description: Enable session recording.
            solveCaptcha:
              type: boolean
              description: Automatically solve captcha challenges.
            timeoutMinutes:
              type: integer
              default: 10
              description: Idle timeout in minutes before the session ends.
    Session:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        cdpWsUrl:
          type: string
          description: Chrome DevTools Protocol WebSocket URL for the session.
        cdpUrl:
          type: string
        webDriverUrl:
          type: string
        profileName:
          type: string
    EnvelopeResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: object
    Envelope:
      type: object
      properties:
        meta:
          type: object
          properties:
            requestId:
              type: string
            status:
              type: string
        errors:
          type: array
          items:
            type: object
        warnings:
          type: array
          items:
            type: object
    SessionsListResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: object
            properties:
              sessions:
                type: array
                items:
                  $ref: '#/components/schemas/Session'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Airtop API key supplied as a Bearer token in the Authorization header: `Authorization: Bearer YOUR_API_KEY`.'