openapi.yaml

openapi: 3.1.0
info:
  title: ATL - iOS Browser & Native App Automation API
  description: |
    iOS Safari and native app automation via HTTP.
    
    ## Modes
    
    ATL operates in two modes:
    - **Browser mode** (default): Safari WebView automation. Pattern: goto → markAll → clickMark
    - **Native mode**: Native iOS app automation. Pattern: openApp → snapshot → tapRef/find
    
    Switch modes with `openApp` (→ native) and `openBrowser` (→ browser).

    ## Quick Start
    ```bash
    ./bin/atl-sim start
    curl http://localhost:9222/ping
    ```

    ## Security Warning

    This API runs an **unauthenticated HTTP server** for local development only.

    - Server binds to 127.0.0.1 (localhost) and rejects external connections
    - Never expose port 9222 to the network or internet
    - Treat this like a browser debug port - it has full control over the WebView
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:9222
    description: Local iOS Simulator (localhost only)

paths:
  /ping:
    get:
      summary: Health check
      operationId: ping
      responses:
        '200':
          description: Server is running
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok]
              example:
                status: ok

  /command:
    post:
      summary: Execute browser command
      operationId: executeCommand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Command'
      responses:
        '200':
          description: Command executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'

components:
  schemas:
    Command:
      type: object
      required: [id, method]
      properties:
        id:
          type: string
          description: Unique request identifier
        method:
          type: string
          enum:
            # Navigation
            - goto
            - reload
            - goBack
            - goForward
            - getURL
            - getTitle
            # Set-of-Mark (main feature)
            - markAll
            - markElements
            - clickMark
            - getMarkInfo
            - unmarkElements
            # Touch Gestures
            - tap
            - longPress
            - swipe
            - pinch
            # Interaction
            - click
            - doubleClick
            - fill
            - type
            - press
            - hover
            - scrollIntoView
            # Capture
            - screenshot
            - captureForVision
            - captureLight
            - captureJPEG
            # Query
            - querySelector
            - querySelectorAll
            - evaluate
            - getDOMSnapshot
            # Waiting
            - waitForSelector
            - waitForReady
            - waitForNavigation
            - waitForAny
            # Cookies
            - getCookies
            - setCookies
            - deleteCookies
            # Native App Mode
            - openApp
            - closeApp
            - appState
            - snapshot
            - tapRef
            - fillRef
            - find
            - openBrowser
        params:
          type: object
          description: Method-specific parameters

    Response:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        result:
          type: object
        error:
          type: string

    # Navigation
    GotoParams:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
          example: https://amazon.com

    # Interaction
    ClickParams:
      type: object
      required: [selector]
      properties:
        selector:
          type: string
          description: CSS selector
          example: "#add-to-cart"

    FillParams:
      type: object
      required: [selector, value]
      properties:
        selector:
          type: string
          example: "input[name=q]"
        value:
          type: string
          example: "airpods pro"

    TypeParams:
      type: object
      required: [text]
      properties:
        text:
          type: string

    PressParams:
      type: object
      required: [key]
      properties:
        key:
          type: string
          enum: [Enter, Tab, Escape, Backspace, ArrowUp, ArrowDown, ArrowLeft, ArrowRight]

    # Touch Gestures
    TapParams:
      type: object
      required: [x, y]
      properties:
        x:
          type: number
          description: X coordinate in viewport
        y:
          type: number
          description: Y coordinate in viewport

    LongPressParams:
      type: object
      required: [x, y]
      properties:
        x:
          type: number
        y:
          type: number
        duration:
          type: number
          default: 0.5
          description: Duration in seconds

    SwipeParams:
      type: object
      properties:
        direction:
          type: string
          enum: [up, down, left, right]
          description: Swipe direction (use this OR from/to coordinates)
        distance:
          type: number
          default: 300
          description: Swipe distance in pixels
        fromX:
          type: number
        fromY:
          type: number
        toX:
          type: number
        toY:
          type: number
        duration:
          type: number
          default: 0.3

    PinchParams:
      type: object
      properties:
        scale:
          type: number
          default: 1.5
          description: Scale factor (>1 zoom in, <1 zoom out)
        duration:
          type: number
          default: 0.3

    GetMarkInfoParams:
      type: object
      required: [label]
      properties:
        label:
          type: integer
          description: Mark label number from markAll/markElements

    GetMarkInfoResult:
      type: object
      properties:
        label:
          type: integer
        text:
          type: string
        tagName:
          type: string
        href:
          type: string
        x:
          type: number
        y:
          type: number
        width:
          type: number
        height:
          type: number

    # Waiting
    WaitForReadyParams:
      type: object
      properties:
        timeout:
          type: number
          default: 10
        stabilityMs:
          type: integer
          default: 500
        selector:
          type: string
          description: Optional selector that must exist

    EvaluateParams:
      type: object
      required: [script]
      properties:
        script:
          type: string
          description: JavaScript to execute in page context

    # Capture
    ScreenshotParams:
      type: object
      properties:
        fullPage:
          type: boolean
          default: false
          description: |
            - false: PNG of viewport
            - true: PDF of entire scrollable page (vector text, searchable)

    ScreenshotResult:
      type: object
      properties:
        data:
          type: string
          format: byte
          description: Base64-encoded PNG or PDF
        mimeType:
          type: string
          enum: [image/png, application/pdf]

    LightCaptureResult:
      type: object
      description: Structured page data (~99% smaller than PDF)
      properties:
        title:
          type: string
        url:
          type: string
          format: uri
        timestamp:
          type: string
          format: date-time
        text:
          type: string
          description: All visible text content
        interactives:
          type: array
          items:
            $ref: '#/components/schemas/InteractiveElement'

    InteractiveElement:
      type: object
      properties:
        tag:
          type: string
          example: A
        id:
          type: string
        text:
          type: string
        href:
          type: string
        ariaLabel:
          type: string

    # Query
    QuerySelectorParams:
      type: object
      required: [selector]
      properties:
        selector:
          type: string

    Element:
      type: object
      properties:
        tag:
          type: string
        id:
          type: string
        className:
          type: string
        text:
          type: string
        href:
          type: string
        value:
          type: string
        rect:
          type: object
          properties:
            x:
              type: number
            y:
              type: number
            width:
              type: number
            height:
              type: number

    # Native App Mode Commands
    OpenAppParams:
      type: object
      required: [bundleId]
      properties:
        bundleId:
          type: string
          description: |
            iOS app bundle identifier to open. Switches to native mode.
            Common bundle IDs:
            - com.apple.Preferences (Settings)
            - com.apple.MobileAddressBook (Contacts)
            - com.apple.calculator (Calculator)
            - com.apple.mobilecal (Calendar)
            - com.apple.mobilenotes (Notes)
          example: com.apple.Preferences

    OpenAppResult:
      type: object
      properties:
        bundleId:
          type: string
        mode:
          type: string
          enum: [native]

    CloseAppParams:
      type: object
      properties:
        bundleId:
          type: string
          description: |
            Bundle ID of app to close. If omitted, closes the current app.
            After closing, remains in native mode with no active app.

    AppStateResult:
      type: object
      description: Returns current automation mode and active app (if any)
      properties:
        mode:
          type: string
          enum: [browser, native]
          description: Current automation mode
        bundleId:
          type: string
          nullable: true
          description: Bundle ID of active native app, or null if in browser mode

    SnapshotParams:
      type: object
      description: |
        Capture accessibility tree of the current native app.
        **Native mode only** - returns error in browser mode.
      properties:
        interactiveOnly:
          type: boolean
          default: false
          description: If true, only return hittable/interactive elements
        maxDepth:
          type: integer
          description: Maximum depth to traverse in element hierarchy

    SnapshotResult:
      type: object
      properties:
        count:
          type: integer
          description: Number of elements returned
        elements:
          type: array
          items:
            $ref: '#/components/schemas/NativeElement'

    NativeElement:
      type: object
      description: Accessibility element from native app
      properties:
        ref:
          type: string
          description: Reference ID for tapRef/fillRef (e.g., "e0", "e1")
          example: e5
        type:
          type: string
          description: XCUIElement type (button, staticText, textField, etc.)
          example: button
        label:
          type: string
          description: Accessibility label
          example: Wi-Fi
        value:
          type: string
          nullable: true
          description: Current value (for text fields, switches, etc.)
        identifier:
          type: string
          description: Accessibility identifier
        x:
          type: number
        y:
          type: number
        width:
          type: number
        height:
          type: number
        isHittable:
          type: boolean
          description: Whether element can receive taps
        isEnabled:
          type: boolean

    TapRefParams:
      type: object
      required: [ref]
      description: |
        Tap an element by its ref from the last snapshot.
        **Native mode only** - returns error in browser mode.
      properties:
        ref:
          type: string
          description: Element reference from snapshot (e.g., "e0", "e5")
          example: e5

    FillRefParams:
      type: object
      required: [ref, text]
      description: |
        Tap a text field by ref, then type text into it.
        **Native mode only** - returns error in browser mode.
      properties:
        ref:
          type: string
          description: Element reference from snapshot
          example: e12
        text:
          type: string
          description: Text to type into the field
          example: John Doe

    FindParams:
      type: object
      required: [text]
      description: |
        Find an element by text/attribute and optionally perform an action.
        **Native mode only** - returns error in browser mode.
      properties:
        text:
          type: string
          description: Text to search for
          example: Wi-Fi
        by:
          type: string
          enum: [any, label, value, identifier, type]
          default: any
          description: Which attribute to search
        action:
          type: string
          enum: [tap, fill, exists, get]
          default: get
          description: |
            Action to perform on found element:
            - tap: Tap the element
            - fill: Tap and type (requires `value` param)
            - exists: Check if element exists (returns found: true/false)
            - get: Return element info without interaction
        value:
          type: string
          description: Text to type (required when action is "fill")

    FindResult:
      type: object
      properties:
        found:
          type: boolean
        ref:
          type: string
          nullable: true
          description: Ref of found element (if found)
        element:
          $ref: '#/components/schemas/NativeElement'
          nullable: true

    OpenBrowserResult:
      type: object
      description: |
        Switch back to browser mode. Closes any active native app.
      properties:
        mode:
          type: string
          enum: [browser]

tags:
  - name: Navigation
    description: Page navigation commands
  - name: Marks
    description: Set-of-Mark labeling system - the core feature
  - name: Touch Gestures
    description: Tap, swipe, pinch at coordinates (works in both modes)
  - name: Interaction
    description: Click, type, fill forms
  - name: Capture
    description: Screenshots, PDFs, structured data (screenshot works in both modes)
  - name: Query
    description: Find elements, execute JavaScript
  - name: Waiting
    description: Wait for selectors, navigation, page ready
  - name: Native Apps
    description: |
      Native iOS app automation. Switch to native mode with `openApp`, back to browser with `openBrowser`.
      
      **Native mode commands:** openApp, closeApp, appState, snapshot, tapRef, fillRef, find, openBrowser
      
      **Commands that work in both modes:** tap, swipe, pinch, screenshot
      
      **Browser-only commands will error in native mode:** goto, markAll, clickMark, evaluate, etc.