asyncapi: 3.0.0
channels:
  ws:
    address: /ws
    description: "Single bidirectional channel carrying every request, response, and subscribed event."
    messages:
      adblockRequest:
        $ref: "#/components/messages/AdblockRequest"
      authRequest:
        $ref: "#/components/messages/AuthRequest"
      bookmarkRequest:
        $ref: "#/components/messages/BookmarkRequest"
      browserEvent:
        $ref: "#/components/messages/BrowserEvent"
      browserRequest:
        $ref: "#/components/messages/BrowserRequest"
      downloadRequest:
        $ref: "#/components/messages/DownloadRequest"
      errorResponse:
        $ref: "#/components/messages/ErrorResponse"
      historyRequest:
        $ref: "#/components/messages/HistoryRequest"
      layoutEvent:
        $ref: "#/components/messages/LayoutEvent"
      layoutRequest:
        $ref: "#/components/messages/LayoutRequest"
      native_appRequest:
        $ref: "#/components/messages/Native_appRequest"
      permissionRequest:
        $ref: "#/components/messages/PermissionRequest"
      pingRequest:
        $ref: "#/components/messages/PingRequest"
      profileRequest:
        $ref: "#/components/messages/ProfileRequest"
      response:
        $ref: "#/components/messages/Response"
      searchRequest:
        $ref: "#/components/messages/SearchRequest"
      search_engineRequest:
        $ref: "#/components/messages/Search_engineRequest"
      settingsRequest:
        $ref: "#/components/messages/SettingsRequest"
      subscribeRequest:
        $ref: "#/components/messages/SubscribeRequest"
      systemEvent:
        $ref: "#/components/messages/SystemEvent"
      workspaceRequest:
        $ref: "#/components/messages/WorkspaceRequest"
    title: MetaDock WebSocket
components:
  messages:
    AdblockRequest:
      name: adblock
      payload:
        $ref: "#/components/schemas/AdblockRequest"
      title: Adblock request
    AuthRequest:
      name: auth
      payload:
        $ref: "#/components/schemas/AuthRequest"
      title: Auth request
    BookmarkRequest:
      name: bookmark
      payload:
        $ref: "#/components/schemas/BookmarkRequest"
      title: Bookmark request
    BrowserEvent:
      name: browser_event
      payload:
        properties:
          browser_uuid:
            description: The subscribed resource this event belongs to.
            format: uuid
            type: string
          data:
            description: Event-specific payload; see x-event-descriptions.
            type: object
          event:
            enum:
              - audio_state_changed
              - download_starting
              - fingerprint_config_changed
              - geo_override_config_changed
              - navigation_completed
              - navigation_starting
              - source_changed
              - title_changed
              - zoom_changed
            type: string
          timestamp:
            description: ISO-8601 emission time.
            format: date-time
            type: string
          type:
            enum:
              - browser_event
            type: string
        required:
          - type
          - event
          - timestamp
          - browser_uuid
        type: object
        x-event-descriptions:
          audio_state_changed: "The browser started or stopped playing audio, or was muted."
          download_starting: A download started in this browser. Carries the source url and target filename.
          fingerprint_config_changed: The anti-fingerprint configuration was applied or updated. Carries the full config.
          geo_override_config_changed: "The geolocation, timezone and locale override configuration was applied or updated. Carries the full config."
          navigation_completed: "A navigation finished. Carries the final url, success flag, and a timestamp."
          navigation_starting: A navigation began in this browser. Carries the target url and a timestamp.
          source_changed: The page source changed after a load or an in-page update.
          title_changed: The document title changed. Carries the new title.
          zoom_changed: The zoom factor changed. Carries the new factor.
      title: Browser event
    BrowserRequest:
      name: browser
      payload:
        $ref: "#/components/schemas/BrowserRequest"
      title: Browser request
    DownloadRequest:
      name: download
      payload:
        $ref: "#/components/schemas/DownloadRequest"
      title: Download request
    ErrorResponse:
      name: error
      payload:
        $ref: "#/components/schemas/ErrorResponse"
      title: Error response
    HistoryRequest:
      name: history
      payload:
        $ref: "#/components/schemas/HistoryRequest"
      title: History request
    LayoutEvent:
      name: layout_event
      payload:
        properties:
          data:
            description: Event-specific payload; see x-event-descriptions.
            type: object
          event:
            enum:
              - deleted
              - renamed
            type: string
          layout_uuid:
            description: The subscribed resource this event belongs to.
            format: uuid
            type: string
          timestamp:
            description: ISO-8601 emission time.
            format: date-time
            type: string
          type:
            enum:
              - layout_event
            type: string
        required:
          - type
          - event
          - timestamp
          - layout_uuid
        type: object
        x-event-descriptions:
          deleted: "The layout was deleted. The envelope's layout_uuid identifies it."
          renamed: The layout was renamed. Carries the new name.
      title: Layout event
    LayoutRequest:
      name: layout
      payload:
        $ref: "#/components/schemas/LayoutRequest"
      title: Layout request
    Native_appRequest:
      name: native_app
      payload:
        $ref: "#/components/schemas/Native_appRequest"
      title: Native_app request
    PermissionRequest:
      name: permission
      payload:
        $ref: "#/components/schemas/PermissionRequest"
      title: Permission request
    PingRequest:
      name: ping
      payload:
        $ref: "#/components/schemas/PingRequest"
      title: Ping request
    ProfileRequest:
      name: profile
      payload:
        $ref: "#/components/schemas/ProfileRequest"
      title: Profile request
    Response:
      name: response
      payload:
        $ref: "#/components/schemas/Response"
      title: Success response
    SearchRequest:
      name: search
      payload:
        $ref: "#/components/schemas/SearchRequest"
      title: Search request
    Search_engineRequest:
      name: search_engine
      payload:
        $ref: "#/components/schemas/Search_engineRequest"
      title: Search_engine request
    SettingsRequest:
      name: settings
      payload:
        $ref: "#/components/schemas/SettingsRequest"
      title: Settings request
    SubscribeRequest:
      name: subscribe
      payload:
        $ref: "#/components/schemas/SubscribeRequest"
      title: Subscribe request
    SystemEvent:
      name: system_event
      payload:
        properties:
          data:
            description: Event-specific payload; see x-event-descriptions.
            type: object
          event:
            enum:
              - layout_created
              - workspace_switched
            type: string
          timestamp:
            description: ISO-8601 emission time.
            format: date-time
            type: string
          type:
            enum:
              - system_event
            type: string
        required:
          - type
          - event
          - timestamp
        type: object
        x-event-descriptions:
          layout_created: "A layout was created. Carries the new layout's uuid and name."
          workspace_switched: "The active workspace changed. Carries the new workspace's id and name."
      title: System event
    WorkspaceRequest:
      name: workspace
      payload:
        $ref: "#/components/schemas/WorkspaceRequest"
      title: Workspace request
  schemas:
    AdblockRequest:
      properties:
        action:
          enum:
            - add
            - enable
            - get_override
            - get_whitelist
            - list
            - list_whitelist
            - remove
            - set_auto_update
            - set_override
            - set_whitelist
            - update
            - update_all
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - adblock
          type: string
      required:
        - type
        - action
      type: object
    AuthRequest:
      properties:
        api_key:
          description: API key carrying the websocket scope. Must be the first message on the connection.
          format: uuid
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        type:
          enum:
            - auth
          type: string
      required:
        - type
        - api_key
      type: object
    BookmarkRequest:
      properties:
        action:
          enum:
            - create
            - create_category
            - delete
            - delete_category
            - list
            - list_categories
            - list_tags
            - open
            - rename_category
            - update
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - bookmark
          type: string
      required:
        - type
        - action
      type: object
    BrowserRequest:
      properties:
        action:
          enum:
            - batch
            - clear_cache
            - clear_console
            - clear_cookies
            - clear_device_emulation
            - clear_fingerprint
            - clear_geo_override
            - clear_geolocation
            - clear_input
            - clear_storage
            - click
            - click_at
            - close_all
            - close_browser
            - close_devtools
            - close_others
            - close_others_in_layout
            - create_browser
            - create_multiple
            - delete_cookie
            - drag
            - emulate_device
            - enable_devtools
            - execute_all
            - execute_js
            - execute_js_with_result
            - extract
            - find
            - forms
            - get_all_browsers
            - get_all_cookies
            - get_browser_state
            - get_console
            - get_cookie
            - get_dialog_policy
            - get_element_attribute
            - get_element_box
            - get_element_text
            - get_emulated_device
            - get_fingerprint
            - get_geo_override
            - get_headers
            - get_last_dialog
            - get_network
            - get_offline
            - get_page_source
            - get_saved_screenshot
            - get_storage
            - get_title
            - get_url
            - get_urls
            - get_user_agent
            - get_viewport
            - get_zoom
            - go_back
            - go_forward
            - history_go
            - hover
            - inject_css
            - inject_script
            - is_element_visible
            - links
            - list_gpu_presets
            - metadata
            - navigate
            - navigate_all
            - open_devtools
            - press_key
            - print_pdf
            - read
            - reload
            - reload_all
            - remove_header
            - right_click
            - screenshot_element
            - scroll_by
            - scroll_to
            - set_cookie
            - set_dialog_policy
            - set_fingerprint
            - set_fingerprint_audio
            - set_fingerprint_canvas
            - set_fingerprint_webgl
            - set_geo_override
            - set_geolocation
            - set_header
            - set_headless
            - set_muted
            - set_offline
            - set_storage
            - set_user_agent
            - set_value
            - set_viewport
            - set_zoom
            - snapshot
            - stop
            - submit_form
            - tables
            - take_screenshot
            - type_text
            - upload_file
            - wait_for_element
            - wait_for_load
            - wait_for_network_idle
          type: string
        browser_uuid:
          description: Target browser. Required by every action except the fleet-wide and create verbs.
          format: uuid
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - browser
          type: string
      required:
        - type
        - action
      type: object
    DownloadRequest:
      properties:
        action:
          enum:
            - cancel
            - clear_all
            - clear_completed
            - get
            - list
            - pause
            - remove
            - resume
            - start
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - download
          type: string
      required:
        - type
        - action
      type: object
    ErrorResponse:
      properties:
        error:
          description: Failure reason.
          type: string
        id:
          description: "Echoes the request's id when one was supplied."
          type: integer
        success:
          enum:
            - false
          type: boolean
      required:
        - success
        - error
      type: object
    HistoryRequest:
      properties:
        action:
          enum:
            - clear
            - delete_visit
            - list
            - profiles
            - remove_uri
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - history
          type: string
      required:
        - type
        - action
      type: object
    LayoutRequest:
      properties:
        action:
          enum:
            - close_all
            - create
            - delete
            - equalize
            - get_apps
            - get_browsers
            - get_info
            - list
            - open_dock
            - rename
            - reset_resolution
            - screenshot
            - set_locked
            - set_mute_all
            - set_resolution
            - toggle_fullscreen
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        layout_uuid:
          description: Target layout.
          format: uuid
          type: string
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - layout
          type: string
      required:
        - type
        - action
      type: object
    Native_appRequest:
      properties:
        action:
          enum:
            - click
            - dismount
            - info
            - list
            - list_processes
            - lock
            - mount
            - press_key
            - screenshot
            - set_title
            - type
            - uia_act
            - uia_tree
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - native_app
          type: string
      required:
        - type
        - action
      type: object
    PermissionRequest:
      properties:
        action:
          enum:
            - clear
            - list
            - list_types
            - remove
            - remove_host
            - set
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - permission
          type: string
      required:
        - type
        - action
      type: object
    PingRequest:
      properties:
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        type:
          enum:
            - ping
          type: string
      required:
        - type
      type: object
    ProfileRequest:
      properties:
        action:
          enum:
            - create
            - create_temporary
            - delete
            - get_default
            - get_proxy
            - list
            - rename
            - set_default
            - set_proxy
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - profile
          type: string
      required:
        - type
        - action
      type: object
    Response:
      properties:
        data:
          description: Action result.
          type: object
        id:
          description: "Echoes the request's id; absent when the request carried none."
          type: integer
        success:
          enum:
            - true
          type: boolean
      required:
        - success
      type: object
    SearchRequest:
      properties:
        action:
          enum:
            - alias_delete
            - alias_list
            - alias_resolve
            - alias_set
            - search
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - search
          type: string
      required:
        - type
        - action
      type: object
    Search_engineRequest:
      properties:
        action:
          enum:
            - create
            - delete
            - list
            - update
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - search_engine
          type: string
      required:
        - type
        - action
      type: object
    SettingsRequest:
      properties:
        action:
          enum:
            - get
            - list
            - list_search_engines
            - list_themes
            - set
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - settings
          type: string
      required:
        - type
        - action
      type: object
    SubscribeRequest:
      properties:
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        subscribe:
          default: true
          description: False unsubscribes from the target.
          type: boolean
        target:
          description: "\"system\", \"browser:<uuid>\", or \"layout:<uuid>\"."
          type: string
        type:
          enum:
            - subscribe
          type: string
      required:
        - type
        - target
      type: object
    WorkspaceRequest:
      properties:
        action:
          enum:
            - create
            - delete
            - get_current
            - get_info
            - get_layouts
            - get_startup
            - list
            - rename
            - set_homepage
            - set_startup
            - switch
          type: string
        id:
          description: Client request id echoed on the response; omit for fire-and-forget.
          type: integer
        params:
          description: "Action arguments. Where the same operation is also reachable over REST, its request body in openapi.yaml documents the same fields."
          type: object
        type:
          enum:
            - workspace
          type: string
      required:
        - type
        - action
      type: object
  securitySchemes:
    apiKey:
      description: "In-band only: the HTTP upgrade carries no credentials. Send {\"type\":\"auth\",\"api_key\":\"<uuid>\"} as the first message."
      type: userPassword
info:
  description: |-
    Real-time WebSocket API for **MetaDock**. Availability of individual actions and
    events depends on your MetaDock edition.

    One WebSocket endpoint at `/ws` carries every message. A client sends a JSON
    object whose `type` selects a handler and whose `action` selects the operation
    within it; arguments go in `params`. Where the same operation is also reachable
    over REST, its request body in `openapi.yaml` documents the same fields.

    ## Authentication
    The HTTP upgrade is not authenticated. The first message on a new connection must
    be `{"type":"auth","api_key":"<uuid>"}`; every other message is rejected until
    it succeeds. Five failed attempts close the socket, and the key must carry the
    `websocket` scope. A key scoped to specific profiles/layouts additionally has
    fleet-wide actions and out-of-scope browsers rejected.

    ## Responses and events
    Every request with an `id` is answered by a response carrying the same `id`.
    Events are pushed only for subscriptions the connection opened with a
    `{"type":"subscribe","target":"..."}` message; an unsubscribed connection
    receives nothing.
  license:
    name: Proprietary
  title: MetaDock WebSocket API
  version: 1.0.0
operations:
  receiveBrowserEvent:
    action: receive
    channel:
      $ref: "#/channels/ws"
    description: Pushed only to connections holding a matching subscription.
    messages:
      - $ref: "#/channels/ws/messages/browserEvent"
  receiveLayoutEvent:
    action: receive
    channel:
      $ref: "#/channels/ws"
    description: Pushed only to connections holding a matching subscription.
    messages:
      - $ref: "#/channels/ws/messages/layoutEvent"
  receiveSystemEvent:
    action: receive
    channel:
      $ref: "#/channels/ws"
    description: Pushed only to connections holding a matching subscription.
    messages:
      - $ref: "#/channels/ws/messages/systemEvent"
  sendAdblock:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/adblockRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendAuth:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/authRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendBookmark:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/bookmarkRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendBrowser:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/browserRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendDownload:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/downloadRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendHistory:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/historyRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendLayout:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/layoutRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendNative_app:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/native_appRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendPermission:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/permissionRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendPing:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/pingRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendProfile:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/profileRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendSearch:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/searchRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendSearch_engine:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/search_engineRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendSettings:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/settingsRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendSubscribe:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/subscribeRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
  sendWorkspace:
    action: send
    channel:
      $ref: "#/channels/ws"
    messages:
      - $ref: "#/channels/ws/messages/workspaceRequest"
    reply:
      channel:
        $ref: "#/channels/ws"
      messages:
        - $ref: "#/channels/ws/messages/response"
        - $ref: "#/channels/ws/messages/errorResponse"
servers:
  local:
    description: Local MetaDock server (host/port configurable)
    host: "127.0.0.1:8080"
    protocol: ws