glasswarp-com Grounding API

openapi: 3.2.0
info:
  title: Glasswarp Platform Grounding 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: Grounding
paths:
  /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:
      - Grounding
      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
  /v1/sessions/{sessionId}/targets:
    get:
      operationId: listTargets
      summary: List click targets (grounding v1)
      description: 'Sparse click targets in native capture coords from the host focused-window

        UI Automation snapshot. Empty if UIA finds nothing or the host is

        unavailable. Clients may still inject CV/grid targets via the SDK.'
      tags:
      - Grounding
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Target list
          content:
            application/json:
              schema:
                type: object
                properties:
                  width:
                    type: integer
                  height:
                    type: integer
                  targets:
                    type: array
                    items:
                      $ref: '#/components/schemas/GroundingTarget'
        '404':
          description: Session not found
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)