glasswarp-com Screenshots API

openapi: 3.2.0
info:
  title: Glasswarp Platform Screenshots API
  version: 1.0.0
  description: 'Real-time visual access and native input control on Windows machines.

    See any screen. Control any PC. One API.


    ## Authentication


    Most `/v1/*` endpoints require a bearer token:


    ```

    Authorization: Bearer gw_live_sk_...

    ```


    Exception: `GET /v1/agent/latest` is public (host auto-update).


    API keys are created in the Console.

    Keys are scoped to your account and can access any rig with API access enabled.


    ## Base URL


    `https://signal.glasswarp.com`'
  contact:
    name: Glasswarp
    url: https://glasswarp.com
  license:
    name: Proprietary
servers:
- url: https://signal.glasswarp.com
  description: Production
security:
- apiKey: []
tags:
- name: Screenshots
paths:
  /v1/sessions/{sessionId}/screenshot:
    get:
      operationId: takeScreenshot
      summary: Take a screenshot
      description: 'Return a JPEG of the current desktop from the host''s last-frame

        buffer (DXGI capture, not VNC). Capture is always native resolution

        (including 4K). Use `max_width` / `quality` to downscale on the host

        for faster LLM ingest. Response headers include both JPEG size and

        native desktop size for click coordinate mapping.'
      tags:
      - Screenshots
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      - name: max_width
        in: query
        required: false
        schema:
          type: integer
          example: 1280
        description: Long-edge cap for the returned JPEG (native capture unchanged)
      - name: quality
        in: query
        required: false
        schema:
          type: integer
          minimum: 40
          maximum: 100
          default: 85
        description: JPEG quality
      - name: x
        in: query
        required: false
        schema:
          type: integer
        description: ROI crop origin X (native capture coords)
      - name: y
        in: query
        required: false
        schema:
          type: integer
        description: ROI crop origin Y
      - name: w
        in: query
        required: false
        schema:
          type: integer
        description: ROI crop width
      - name: h
        in: query
        required: false
        schema:
          type: integer
        description: ROI crop height
      responses:
        '200':
          description: JPEG screenshot
          headers:
            X-Screenshot-Width:
              schema:
                type: integer
              description: Width of the returned JPEG
            X-Screenshot-Height:
              schema:
                type: integer
              description: Height of the returned JPEG
            X-Screenshot-Native-Width:
              schema:
                type: integer
              description: Native desktop capture width (use for clicks)
            X-Screenshot-Native-Height:
              schema:
                type: integer
              description: Native desktop capture height (use for clicks)
            X-Capture-Mode:
              schema:
                type: string
                enum:
                - dxgi
                - gdi
                - gdi_fallback
                - unknown
              description: Host API capture path for this frame (updates mid-session)
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        '504':
          description: Screenshot timed out (host did not respond within 5s)
        '503':
          description: 'Capture recovering (DXGI AccessLost reacquire). Do not act on a

            frame — retry after ~2s. Body `code=capture_recovering`.

            '
  /v1/sessions/{sessionId}/dirty:
    get:
      operationId: getDirtyRects
      summary: Get accumulated dirty rectangles
      description: 'Returns DXGI `GetFrameDirtyRects` accumulated since the last poll, in

        capture-buffer coordinates `[x, y, w, h]`. When `available` is false

        (GDI capture fallback), dirty metadata is absent — treat as assume

        changed, never as "no change". Empty `rects` with `available: true`

        means no visual change. Pair with ROI screenshot (`x,y,w,h`) when

        dirty is available.'
      tags:
      - Screenshots
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Dirty rects since last take
          content:
            application/json:
              schema:
                type: object
                properties:
                  width:
                    type: integer
                  height:
                    type: integer
                  available:
                    type: boolean
                    description: False when dirty metadata is unavailable (GDI fallback)
                  capture_mode:
                    type: string
                    enum:
                    - dxgi
                    - gdi
                    - gdi_fallback
                    - unknown
                  rects:
                    type: array
                    items:
                      type: array
                      items:
                        type: integer
                      minItems: 4
                      maxItems: 4
        '504':
          description: Dirty request timed out
  /v1/sessions/{sessionId}/observe:
    get:
      operationId: observeSession
      summary: 'Observe: frame, changes, and click targets in one round trip'
      description: 'One-round-trip agent observe: JPEG (same options as screenshot),

        dirty rects take, and sparse click targets from the host UI Automation

        snapshot. Response includes structured `text` (window title + readable

        target lines), `changed` (false only when DXGI dirty is available and

        empty; true when dirty is unavailable — assume changed), and

        `capture_mode` (`dxgi` | `gdi_fallback` | `unknown`; legacy `gdi` = `gdi_fallback`).


        Password / masked fields are redacted in `text` and target `value`

        (`masked=true`, value always `[redacted]`).


        Set `image=0` for text/targets-only verification (skips JPEG encode —

        much faster). Prefer `max_width=960` and `quality=60` for cheap

        verification-grade frames when you do need an image.


        SDK applies Set-of-Mark when `mark=1` and targets are present.

        Coords are native capture space.'
      tags:
      - Screenshots
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      - name: max_width
        in: query
        schema:
          type: integer
          example: 1280
      - name: quality
        in: query
        schema:
          type: integer
          minimum: 40
          maximum: 100
      - name: x
        in: query
        schema:
          type: integer
      - name: y
        in: query
        schema:
          type: integer
      - name: w
        in: query
        schema:
          type: integer
      - name: h
        in: query
        schema:
          type: integer
      - name: mark
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
        description: Request SoM marking when host targets are non-empty (ignored when image=0)
      - name: image
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 1
        description: 'Set to 0 for text/targets-only observe (no JPEG). Use for simple

          verification — did the dialog close? is the field focused?

          '
      responses:
        '200':
          description: Observe payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObserveResult'
        '503':
          description: 'Capture recovering (DXGI AccessLost reacquire). Retry — do not

            treat as a blank frame. Body `code=capture_recovering`.

            '
        '504':
          description: Screenshot timed out
components:
  schemas:
    ObserveText:
      type: object
      description: Compact structured text for agent decisions without image tokens
      properties:
        window_title:
          type: string
          example: Save As
        window_role:
          type: string
          example: window
        targets:
          type: array
          items:
            type: string
          example:
          - '[1] Filename (edit, focused)'
          - '[2] Save (button)'
        summary:
          type: string
          example: 'Focused: "Save As" (window); 2 target(s)'
    GroundingTarget:
      type: object
      required:
      - id
      - x
      - y
      - w
      - h
      properties:
        id:
          type: string
          description: Stable id for click_target / SoM mark
        x:
          type: integer
          description: Native capture origin X
        y:
          type: integer
          description: Native capture origin Y
        w:
          type: integer
        h:
          type: integer
        role:
          type: string
          example: button
        name:
          type: string
          example: Submit
        source:
          type: string
          enum:
          - uia
          - cv
          - grid
          - client
          description: Where the target came from
        focused:
          type: boolean
          description: True when this control has keyboard focus
        masked:
          type: boolean
          description: Password / masked field — value is always redacted
        value:
          type: string
          description: 'ValuePattern text when available. Always `[redacted]` when

            `masked` is true — plaintext passwords are never returned.

            '
    ObserveResult:
      type: object
      properties:
        width:
          type: integer
        height:
          type: integer
        native_width:
          type: integer
        native_height:
          type: integer
        timestamp:
          type: integer
        jpeg_base64:
          type: string
          format: byte
          description: Omitted when `image=0` (text/targets-only observe)
        dirty:
          type: object
          nullable: true
          description: 'Accumulated DXGI dirty rects since the last take, or null when dirty metadata is unavailable (GDI capture fallback). Never a synthesized full-frame rect. Null ⇒ agents should assume changed.

            '
          properties:
            width:
              type: integer
            height:
              type: integer
            available:
              type: boolean
              description: Always true when dirty is present; absent dirty uses null.
            rects:
              type: array
              items:
                type: array
                items:
                  type: integer
        changed:
          type: boolean
          description: 'False only when DXGI dirty was available and empty. True when dirty is null/unavailable (assume changed) or when rects exist.

            '
        capture_mode:
          type: string
          enum:
          - dxgi
          - gdi
          - gdi_fallback
          - unknown
          description: Host API capture path (updates mid-session on DXGI loss → GDI fallback)
        targets:
          type: array
          items:
            $ref: '#/components/schemas/GroundingTarget'
        text:
          $ref: '#/components/schemas/ObserveText'
        marked:
          type: boolean
        timing:
          type: object
          description: 'Server-side timing for this observe (milliseconds). Host fields are

            null until the paired host daemon reports them.

            '
          properties:
            total_ms:
              type: integer
              description: Wall-clock for the whole observe on the gateway
            screenshot_rtt_ms:
              type: integer
              description: Gateway ↔ host RTT for the screenshot leg (0 when image=0)
            dirty_rtt_ms:
              type: integer
              description: Gateway ↔ host RTT for the dirty-rects leg
            targets_rtt_ms:
              type: integer
              description: Gateway ↔ host RTT for the UIA targets leg
            host_jpeg_ms:
              type: integer
              nullable: true
              description: Host-side capture + JPEG encode time when reported
            host_uia_ms:
              type: integer
              nullable: true
              description: Host-side UIA snapshot time when reported
            image:
              type: boolean
              description: Whether a JPEG was requested
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: API key in the format `gw_(live|test)_sk_<hex>`
    userJwt:
      type: http
      scheme: bearer
      description: Supabase user JWT (for console/dashboard endpoints)