openapi.yaml

# SPDX-License-Identifier: Apache-2.0
#
# https://www.apache.org/licenses/LICENSE-2.0
openapi: 3.1.0
info:
  title: Visdom API
  description: >
    Visdom is a flexible tool for creating, organizing, and sharing
    visualizations of live, rich data. It supports Plotly-based charts,
    images, text, audio, video, embeddings, and more. This specification
    documents the HTTP REST endpoints exposed by the Visdom Tornado server.


    All POST endpoints accept JSON request bodies (`application/json`).
    When authentication is enabled, most endpoints require a valid session
    cookie (set via the login endpoint at `POST /`). Unauthenticated
    requests currently receive a `400` status code.


    The server also supports WebSocket connections at `/socket` (read-only
    subscriber) and `/vis_socket` (write-capable visualization source), as
    well as HTTP polling fallbacks at `/socket_wrap` and `/vis_socket_wrap`.
  version: 0.3.0
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: Visdom Authors
    url: https://github.com/fossasia/visdom

servers:
  - url: "{protocol}://{host}:{port}{base_url}"
    description: Visdom server
    variables:
      protocol:
        default: http
        enum: [http, https]
      host:
        default: "0.0.0.0"
        description: Server hostname or IP address
      port:
        default: "8097"
        description: Server port
      base_url:
        default: ""
        description: Optional base URL prefix (e.g., "/visdom")

tags:
  - name: Visualization
    description: Create and update visualization windows (panes)
  - name: Window Management
    description: Query, close, and retrieve window data
  - name: Environment
    description: Manage environments (create, delete, fork, list, save, compare)
  - name: Experiments
    description: Track experiment metadata (hyper-parameters, metrics, tags)
  - name: Authentication
    description: Login and session management
  - name: Socket Polling
    description: HTTP polling fallbacks for WebSocket connections
  - name: System
    description: Health check and diagnostics

security:
  - cookieAuth: []
  - {}

paths:
  /events:
    post:
      operationId: createWindow
      tags: [Visualization]
      summary: Create a new visualization window
      description: >
        Creates a new visualization pane in the specified environment. The
        window type is determined by `data[].type`. If `win` is omitted, a
        new window ID is generated automatically. If `win` is provided and
        already exists, the existing window is replaced.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWindowRequest"
      responses:
        "200":
          description: Window created successfully. Returns the window ID as plain text.
          content:
            text/plain:
              schema:
                type: string
                description: The ID of the created window.
                examples:
                  - "window_38fa9db8e4f5b2"
        "400":
          description: Authentication required but not provided (when login is enabled).

  /update:
    post:
      operationId: updateWindow
      tags: [Visualization]
      summary: Update an existing visualization window
      description: >
        Updates the data, options, or layout of an existing window. Supports
        appending data to scatter/line plots, updating heatmaps (append/prepend
        rows or columns), appending text, managing image history, updating
        embeddings selections, adding/removing traces, and modifying plot
        options or layout properties. If `append` is true and the window does
        not exist, a new window is created -- laid out with `layout_create`
        when the request carries it, since an append itself sends an empty
        `layout` by design.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWindowRequest"
      responses:
        "200":
          description: >
            Window updated successfully. Returns the window ID, or an error
            message string if the window does not exist or the update is not
            supported for the window type.
          content:
            text/plain:
              schema:
                type: string
              examples:
                success:
                  value: "window_38fa9db8e4f5b2"
                not_found:
                  value: "win does not exist"
                unsupported:
                  value: "win is not scatter, heatmap, custom, image_history, embeddings, or text; was bar"
        "400":
          description: Authentication required but not provided (when login is enabled).

  /close:
    post:
      operationId: closeWindow
      tags: [Window Management]
      summary: Close one or all windows in an environment
      description: >
        Closes (deletes) a specific window or all windows in the given
        environment. The close event is broadcast to all subscribed clients.
        If `win` is omitted or null, all windows in the environment are
        closed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                win:
                  type:
                    - string
                    - "null"
                  description: >
                    Window ID to close. If null or omitted, all windows in
                    the environment are closed.
                eid:
                  type:
                    - string
                    - "null"
                  description: >
                    Environment ID. Defaults to `"main"` if omitted.
      responses:
        "200":
          description: >
            Window(s) closed. A close broadcast is sent to all subscribed
            clients. No body is returned.
        "400":
          description: Authentication required but not provided (when login is enabled).

  /win_exists:
    post:
      operationId: checkWindowExists
      tags: [Window Management]
      summary: Check if a window exists in an environment
      description: >
        Returns `"true"` or `"false"` (as a plain text string) indicating
        whether the specified window exists in the given environment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [win]
              properties:
                win:
                  type: string
                  description: Window ID to check.
                eid:
                  type:
                    - string
                    - "null"
                  description: >
                    Environment ID. Defaults to `"main"` if omitted.
      responses:
        "200":
          description: Returns `"true"` or `"false"` as plain text.
          content:
            text/plain:
              schema:
                type: string
                enum: ["true", "false"]
        "400":
          description: Authentication required but not provided (when login is enabled).

  /win_data:
    post:
      operationId: getOrSetWindowData
      tags: [Window Management]
      summary: Get or set raw window/environment data
      description: >
        When `data` is absent, retrieves the raw JSON data for a specific
        window (if `win` is provided) or all windows in an environment (if
        `win` is null). When `data` is present, sets (overwrites) the
        window or environment data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/GetWindowDataRequest"
                - $ref: "#/components/schemas/SetWindowDataRequest"
      responses:
        "200":
          description: >
            For GET operations: returns JSON data of the window or all
            windows. For SET operations: no body, but broadcasts an
            environment update.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/WindowObject"
                  - type: object
                    additionalProperties:
                      $ref: "#/components/schemas/WindowObject"
                    description: Map of window IDs to window objects (when win is null).
        "400":
          description: Authentication required but not provided (when login is enabled).
        "500":
          description: >
            Server error. Occurs if the requested window does not exist
            (unhandled assertion error).

  /save:
    post:
      operationId: saveEnvironments
      tags: [Environment]
      summary: Persist environments to disk
      description: >
        Saves the specified environments to JSON files on disk. Environment
        IDs that do not exist in the current server state are silently
        dropped. Returns the list of environment IDs that were actually
        saved.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [data]
              properties:
                data:
                  type: array
                  items:
                    type: string
                  description: List of environment IDs to save.
                  examples:
                    - ["main", "experiment_1"]
      responses:
        "200":
          description: Returns JSON array of successfully saved environment IDs.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                examples:
                  - ["main", "experiment_1"]
        "400":
          description: Authentication required but not provided (when login is enabled).

  /delete_env:
    post:
      operationId: deleteEnvironment
      tags: [Environment]
      summary: Delete an environment
      description: >
        Permanently deletes an environment and its associated JSON file on
        disk. The `"main"` environment cannot be deleted (the request is
        silently ignored). After deletion, an `env_update` broadcast is
        sent to all subscribed clients. Handles both standard and
        hash-named environment files.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                eid:
                  type: string
                  description: >
                    Environment ID to delete. Forward/backward slashes are
                    replaced with underscores.
      responses:
        "200":
          description: >
            Environment deleted (or silently ignored if `"main"`). An
            `env_update` broadcast is sent. No body returned.
        "400":
          description: Authentication required but not provided (when login is enabled).

  /env_state:
    post:
      operationId: listEnvironments
      tags: [Environment]
      summary: List all available environments
      description: >
        Returns a JSON array of all environment IDs currently loaded in
        the server state. The request body is ignored but must be valid
        JSON (an empty object `{}` is sufficient).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body is ignored. Send an empty object.
      responses:
        "200":
          description: JSON array of environment IDs.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                examples:
                  - ["main", "experiment_1", "experiment_2"]
        "400":
          description: Authentication required but not provided (when login is enabled).

  /fork_env:
    post:
      operationId: forkEnvironment
      tags: [Environment]
      summary: Clone an environment with a new ID
      description: >
        Deep-copies the source environment (all windows and metadata) into
        a new environment with the specified ID. The forked environment is
        immediately saved to disk and an `env_update` broadcast is sent.
        Fails with an assertion error if the source environment does not
        exist.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prev_eid, eid]
              properties:
                prev_eid:
                  type: string
                  description: Source environment ID to clone from.
                eid:
                  type: string
                  description: New environment ID for the clone.
      responses:
        "200":
          description: Returns the new environment ID as plain text.
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Authentication required but not provided (when login is enabled).
        "500":
          description: Server error. Occurs if the source environment does not exist (unhandled assertion error).

  /experiments/log:
    post:
      operationId: logExperiment
      tags: [Experiments]
      summary: Record experiment metadata for an environment
      description: >
        Attaches experiment metadata (hyper-parameters, metric observations,
        and tags) to an environment, stored under the environment's
        `experiment` key and persisted through the server's data store. The
        `action` field selects the operation:


        - `log` (default): create or update the experiment. Repeated calls
        merge new `params`/`tags` and overwrite `name`/`description`.


        - `metrics`: append one or more `{name: value}` observations at an
        optional `step`, creating the experiment if it does not exist yet.


        - `finish`: mark the experiment terminal (`finished` or `failed`). An
        experiment that is already terminal cannot be finished again.


        Once an experiment is terminal, every action is rejected with `409`, so
        neither a finished run's recorded data nor its final status can change
        after the fact.
        Every action writes, so the endpoint is rejected with `403` when the
        server is running in readonly mode.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                eid:
                  type: string
                  description: Target environment ID. Defaults to `main`.
                action:
                  type: string
                  enum: [log, metrics, finish]
                  default: log
                  description: Operation to perform.
                name:
                  type: string
                  description: Display name (action `log`). Defaults to the eid.
                description:
                  type: string
                  description: Free-form description (action `log`).
                params:
                  type: object
                  additionalProperties: true
                  description: 'Hyper-parameters as `{name: value}` (action `log`).'
                tags:
                  type: object
                  additionalProperties: true
                  description: 'Free-form tags as `{name: value}` (action `log`).'
                metrics:
                  type: object
                  additionalProperties:
                    type: number
                  description: >
                    Metric observations as `{name: value}` (action `metrics`).
                    Must be a non-empty object.
                step:
                  type: integer
                  description: Optional training step for the metrics (action `metrics`).
                status:
                  type: string
                  enum: [finished, failed]
                  default: finished
                  description: Terminal status (action `finish`).
      responses:
        "200":
          description: The stored experiment as JSON.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Experiment"
        "400":
          description: >
            Invalid request — unknown `action`, non-object `params`/`tags`/`metrics`,
            empty `metrics`, or a non-terminal `finish` status. Also returned when
            authentication is required but not provided.
        "403":
          description: >
            Experiment logging is disabled because the server is in readonly
            mode.
        "404":
          description: A `finish` was requested for an env that has no experiment.
        "409":
          description: >
            A write was attempted on a terminal (finished/failed) experiment —
            a `log`/`metrics` call, or a second `finish`.

  /experiments/search:
    post:
      operationId: searchExperiments
      tags: [Experiments]
      summary: Search experiments across all environments
      description: >
        Returns the experiments matching `query`, sorted and paged. The query is
        a small readable syntax of comparisons (`<`, `<=`, `>`, `>=`, `=`, `!=`,
        `contains`) combined with `AND`/`OR` and parentheses, for example
        `lr < 0.01 AND (acc > 0.9 OR status = finished)`. Omitting `query`
        matches every experiment.


        Comparison names are the experiment's built-in fields (`name`,
        `status`, `created_at`, ...), its params, its metrics and its tags. A
        name may be given bare (`acc`) or namespaced when it is ambiguous
        (`metric.acc`, `param.lr`, `tag.owner`); metrics compare on their latest
        logged value. A name no experiment has simply matches nothing.


        Queries are parsed into a predicate and evaluated in Python — never
        eval'd and never turned into SQL — so a hostile query is rejected as a
        parse error rather than executed.


        Experiments are read back through the server's data store, so a server
        running with no persistence path configured has nothing to search.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  nullable: true
                  description: >
                    Filter expression. Omitted, null or blank matches every
                    experiment.
                sort_by:
                  type: string
                  nullable: true
                  default: created_at
                  description: >
                    Field to sort by — any name a query can compare on.
                    Experiments lacking the field sort last in both directions.
                descending:
                  type: boolean
                  default: true
                  description: Sort direction; newest/highest first by default.
                limit:
                  type: integer
                  nullable: true
                  minimum: 0
                  maximum: 1000
                  default: 100
                  description: >
                    Maximum number of experiments in the reply, capped at 1000.
                    `0` returns just the count; `null` asks for as many as the
                    cap allows. A `limit` above the cap is coerced down to it
                    rather than rejected, and the reply reports the `limit` it
                    actually applied. `total` is never capped.
                offset:
                  type: integer
                  minimum: 0
                  maximum: 10000
                  default: 0
                  description: >
                    Number of matches to skip before the returned page.
                    `offset` + `limit` must not exceed 10000: a deep page is
                    found by ranking everything above it, so its cost is its
                    depth. Unlike `limit` this is rejected rather than coerced,
                    since a changed `offset` would silently return a different
                    page. Read past the window by narrowing `query`.
      responses:
        "200":
          description: The matching page of experiments.
          content:
            application/json:
              schema:
                type: object
                required: [experiments, total, limit, offset, query]
                properties:
                  experiments:
                    type: array
                    description: One page of matching experiments.
                    items:
                      $ref: "#/components/schemas/Experiment"
                  total:
                    type: integer
                    description: >
                      Total matches for the query, ignoring `limit`/`offset`.
                  limit:
                    type: integer
                    description: >
                      The limit actually applied to this reply, after the cap.
                      Never `null`: a request that asked for everything is
                      answered with the number it was given.
                  offset:
                    type: integer
                    description: The offset applied to this reply.
                  query:
                    type: string
                    description: The query used, `""` if none was given.
        "400":
          description: >
            Invalid request — a body that is not a JSON object, malformed
            `query` syntax, a non-string `query`/`sort_by`, a `limit`/`offset`
            that is not a non-negative integer, or an `offset` + `limit` past
            the 10000 window. Also returned when authentication is required but
            not provided.

  /experiments/compare:
    post:
      operationId: compareExperiments
      tags: [Experiments]
      summary: Compare experiments field by field
      description: >
        Lines several experiments up beside each other and reports, per section
        (params, metrics and tags), which fields they agree on and which they do
        not — the short list of knobs that actually changed between runs.


        The runs are named by `env_ids` and compared in the order given; every id
        must have an experiment, otherwise `404`.


        Finding the runs is `/experiments/search`'s job: it answers "which runs
        match?", this answers "how do these runs differ?". To compare a query's
        matches, search first and pass the resulting ids on.


        Metrics are a time series, so a comparison uses each metric's latest
        observation — the same value a search compares on.


        Experiments are read back through the server's data store, so a server
        running with no persistence path configured has nothing to compare.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [env_ids]
              properties:
                env_ids:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  description: >
                    Environments to compare, in the order given. Duplicate ids
                    collapse to one. At most 1000 per request, matching the
                    largest page `/experiments/search` returns, since every
                    named run is loaded and echoed back in full. A longer list
                    is rejected rather than truncated — a diff of some of the
                    runs asked for is a different answer, not a smaller one.
                  items:
                    type: string
      responses:
        "200":
          description: The comparison of the selected experiments.
          content:
            application/json:
              schema:
                type: object
                required: [env_ids, experiments, params, metrics, tags]
                properties:
                  env_ids:
                    type: array
                    description: The runs compared, in the order compared.
                    items:
                      type: string
                  experiments:
                    type: array
                    description: The compared experiments, in full.
                    items:
                      $ref: "#/components/schemas/Experiment"
                  params:
                    $ref: "#/components/schemas/ExperimentComparisonSection"
                  metrics:
                    $ref: "#/components/schemas/ExperimentComparisonSection"
                  tags:
                    $ref: "#/components/schemas/ExperimentComparisonSection"
        "400":
          description: >
            Invalid request — the body is not a JSON object, or `env_ids` is
            missing, empty, not a list, names more than 1000 environments, or
            holds something other than strings.
            Also returned when authentication is required but not provided.
        "404":
          description: One or more of the given `env_ids` has no experiment.

  /experiments/suggest:
    post:
      operationId: suggestExperiment
      tags: [Experiments]
      summary: Suggest parameters for the next run (reserved)
      description: >
        Reserved endpoint for hyper-parameter suggestion. Choosing the next set
        of parameters to try is a search-strategy problem (Optuna-backed) that
        lands in a later release, so this is currently a stub: it accepts the
        request and replies `501 Not Implemented` with a JSON body carrying a
        `suggestion: null` placeholder, rather than a made-up suggestion. The
        route, the `suggest_experiment` client method and this documentation are
        in place so the strategy can be wired in later without changing the
        surface.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                eid:
                  type: string
                  description: Target environment ID. Defaults to `main`.
                params:
                  type: object
                  additionalProperties: true
                  description: >
                    The search space to suggest over, as `{name: spec}`. Ignored
                    by the stub; reserved for the eventual strategy.
      responses:
        "501":
          description: >
            Not implemented — the suggestion strategy is reserved for a later
            release. The body is a JSON stub.
          content:
            application/json:
              schema:
                type: object
                required: [status, detail, suggestion]
                properties:
                  status:
                    type: string
                    example: not_implemented
                  detail:
                    type: string
                  suggestion:
                    nullable: true
                    description: Always `null` while the endpoint is a stub.
        "400":
          description: >
            Invalid request — the body is present but is not valid JSON, or is
            not a JSON object. Also returned when authentication is required
            but not provided.

  /experiments/tags:
    get:
      operationId: getEnvironmentTags
      tags: [Experiments]
      summary: Read experiment tags for environments
      description: >
        Returns one environment's key/value tag mapping when `eid` is supplied,
        or an `{eid: {name: value}}` mapping for all tagged environments.
        Tags are stored in the existing `Experiment.tags` metadata; no separate
        tag index or persistence format is maintained.
      parameters:
        - in: query
          name: eid
          schema:
            type: string
          description: Optional environment ID.
      responses:
        "200":
          description: One tag mapping or all environment tag mappings.
        "401":
          description: Authentication required but not provided.
    post:
      operationId: updateEnvironmentTags
      tags: [Experiments]
      summary: Read, replace, or append environment tags
      description: >
        With `action: set` (the default), replaces an environment's tags or
        appends them when `append` is true. `action: get` reads the same data as
        GET while allowing later clients to use the shared POST transport.
        The `tags` field is required for `set`; an explicit empty object clears
        the environment's tags.
        Tag changes are allowed for completed experiments because they are
        organizational metadata. Successful writes broadcast `tags_update` to
        both WebSocket and polling browser clients.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum: [get, set]
                  default: set
                eid:
                  type: string
                  description: Target environment. Defaults to `main` for set.
                tags:
                  type: object
                  maxProperties: 20
                  description: >
                    Required for `action: set`. String tag names mapped to string
                    values. Names are limited to 50 characters by the domain
                    layer. An empty object explicitly clears all tags.
                  additionalProperties:
                    type: string
                append:
                  type: boolean
                  default: false
      responses:
        "200":
          description: The resulting tags, or the requested tag mapping.
        "400":
          description: >
            Invalid action, missing or invalid tag mapping, tag limit, or append
            flag.
        "401":
          description: Authentication required but not provided.
        "403":
          description: Tag writes are disabled in readonly mode.

  /experiments/hparams:
    post:
      operationId: createHparamsPane
      tags: [Experiments]
      summary: Open a hyper-parameter pane over logged experiments
      description: >
        Selects experiments, flattens them into a table of hyper-parameters
        against their latest metric values (and tags), and registers a
        dedicated `hparams` window with that content. The window is written
        into the env state, broadcast to connected clients, and the
        environment is saved immediately, so the pane is on disk without an
        explicit save.


        `mode` chooses how the runs are selected; when omitted it is inferred
        from which of `query`/`env_ids` were supplied:


        - `query`: the runs matching `query` (the syntax of
        `/experiments/search`). The query must be non-empty and `env_ids`
        must not be given.


        - `env_ids`: the runs named in `env_ids`, in that order. `env_ids`
        must be non-empty and `query` must not be given; missing envs are
        skipped rather than an error.


        - `both`: the intersection — runs matching `query` and named in
        `env_ids`, ordered by `env_ids`. Both must be given and non-empty.


        There is no "show everything" call: with neither `query` nor
        `env_ids` there is nothing to select (400). A blank query counts as
        no query. The resolved selection is stored on the window so a later
        `/experiments/hparams/update` can re-run it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                eid:
                  type: string
                  description: Environment to register the pane in. Defaults to `main`.
                query:
                  type: string
                  description: Selection query, e.g. `lr < 0.01 AND acc > 0.9`.
                env_ids:
                  type: array
                  items:
                    type: string
                  description: Explicit environment ids, kept in the order given.
                mode:
                  type: string
                  enum: [query, env_ids, both]
                  description: How the runs are selected. Inferred when omitted.
                win:
                  type: string
                  description: Window ID to register the pane under. Autogenerated when omitted.
                opts:
                  type: object
                  additionalProperties: true
                  description: Window options (`title` defaults to `Hyperparameters`).
      responses:
        "200":
          description: The created window ID as plain text.
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: >
            Invalid request — no selection given, a mode/argument combination
            that is not allowed, a malformed `query`, or non-string `env_ids`.
            Also returned when authentication is required but not provided.
        "403":
          description: >
            Creating a pane writes a window, so it is disabled because the
            server is in readonly mode.

  /experiments/hparams/update:
    post:
      operationId: updateHparamsPane
      tags: [Experiments]
      summary: Change or refresh an existing hyper-parameter pane
      description: >
        The dedicated write path for `hparams` windows — the generic `/update`
        endpoint only understands plot-shaped content. The target `win` must
        name an existing window of type `hparams`.


        With `query`/`env_ids`/`mode` in the body the pane's selection is
        replaced, under exactly the rules of `/experiments/hparams`. With none
        of them the selection stored on the window is re-run — a manual
        refresh that picks up runs logged (or newly matching) since the pane
        was built.


        The rebuilt window keeps its id and position but carries a fresh
        `contentID`; it is broadcast to the environment's subscribers and the
        environment is saved, so state and disk reflect the update
        immediately. `opts` overrides the pane's title/size; when omitted the
        current ones are kept.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [win]
              properties:
                win:
                  type: string
                  description: ID of the hparams window to update.
                eid:
                  type: string
                  description: Environment holding the window. Defaults to `main`.
                query:
                  type: string
                  description: Replacement selection query.
                env_ids:
                  type: array
                  items:
                    type: string
                  description: Replacement explicit environment ids.
                mode:
                  type: string
                  enum: [query, env_ids, both]
                  description: How the replacement selection works. Inferred when omitted.
                opts:
                  type: object
                  additionalProperties: true
                  description: Overrides for the pane's window options.
      responses:
        "200":
          description: The updated window ID as plain text.
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: >
            Invalid request — `win` missing, the window is not an `hparams`
            window, a bare refresh on a window with no stored selection, or an
            invalid replacement selection. Also returned when authentication
            is required but not provided.
        "403":
          description: >
            Updating a pane writes to the env, so it is disabled because the
            server is in readonly mode. Checked before the target window is
            looked up, so a refused request reveals nothing about it.
        "404":
          description: The environment or the window does not exist.

  /experiments/hparams:
    post:
      operationId: createHparamsPane
      tags: [Experiments]
      summary: Open a hyper-parameter pane over logged experiments
      description: >
        Selects experiments, flattens them into a table of hyper-parameters
        against their latest metric values (and tags), and registers a
        dedicated `hparams` window with that content. The window is written
        into the env state, broadcast to connected clients, and the
        environment is saved immediately, so the pane is on disk without an
        explicit save.


        `mode` chooses how the runs are selected; when omitted it is inferred
        from which of `query`/`env_ids` were supplied:


        - `query`: the runs matching `query` (the syntax of
        `/experiments/search`). The query must be non-empty and `env_ids`
        must not be given.


        - `env_ids`: the runs named in `env_ids`, in that order. `env_ids`
        must be non-empty and `query` must not be given; missing envs are
        skipped rather than an error.


        - `both`: the intersection — runs matching `query` and named in
        `env_ids`, ordered by `env_ids`. Both must be given and non-empty.


        There is no "show everything" call: with neither `query` nor
        `env_ids` there is nothing to select (400). A blank query counts as
        no query. The resolved selection is stored on the window so a later
        `/experiments/hparams/update` can re-run it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                eid:
                  type: string
                  description: Environment to register the pane in. Defaults to `main`.
                query:
                  type: string
                  description: Selection query, e.g. `lr < 0.01 AND acc > 0.9`.
                env_ids:
                  type: array
                  items:
                    type: string
                  description: Explicit environment ids, kept in the order given.
                mode:
                  type: string
                  enum: [query, env_ids, both]
                  description: How the runs are selected. Inferred when omitted.
                win:
                  type: string
                  description: Window ID to register the pane under. Autogenerated when omitted.
                opts:
                  type: object
                  additionalProperties: true
                  description: Window options (`title` defaults to `Hyperparameters`).
      responses:
        "200":
          description: The created window ID as plain text.
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: >
            Invalid request — no selection given, a mode/argument combination
            that is not allowed, a malformed `query`, or non-string `env_ids`.
            Also returned when authentication is required but not provided.
        "403":
          description: >
            Creating a pane writes a window, so it is disabled because the
            server is in readonly mode.

  /experiments/hparams/update:
    post:
      operationId: updateHparamsPane
      tags: [Experiments]
      summary: Change or refresh an existing hyper-parameter pane
      description: >
        The dedicated write path for `hparams` windows — the generic `/update`
        endpoint only understands plot-shaped content. The target `win` must
        name an existing window of type `hparams`.


        With `query`/`env_ids`/`mode` in the body the pane's selection is
        replaced, under exactly the rules of `/experiments/hparams`. With none
        of them the selection stored on the window is re-run — a manual
        refresh that picks up runs logged (or newly matching) since the pane
        was built.


        The rebuilt window keeps its id and position but carries a fresh
        `contentID`; it is broadcast to the environment's subscribers and the
        environment is saved, so state and disk reflect the update
        immediately. `opts` overrides the pane's title/size; when omitted the
        current ones are kept.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [win]
              properties:
                win:
                  type: string
                  description: ID of the hparams window to update.
                eid:
                  type: string
                  description: Environment holding the window. Defaults to `main`.
                query:
                  type: string
                  description: Replacement selection query.
                env_ids:
                  type: array
                  items:
                    type: string
                  description: Replacement explicit environment ids.
                mode:
                  type: string
                  enum: [query, env_ids, both]
                  description: How the replacement selection works. Inferred when omitted.
                opts:
                  type: object
                  additionalProperties: true
                  description: Overrides for the pane's window options.
      responses:
        "200":
          description: The updated window ID as plain text.
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: >
            Invalid request — `win` missing, the window is not an `hparams`
            window, a bare refresh on a window with no stored selection, or an
            invalid replacement selection. Also returned when authentication
            is required but not provided.
        "403":
          description: >
            Updating a pane writes to the env, so it is disabled because the
            server is in readonly mode. Checked before the target window is
            looked up, so a refused request reveals nothing about it.
        "404":
          description: The environment or the window does not exist.

  /upload_env:
    post:
      operationId: uploadEnvironment
      tags: [Environment]
      summary: Upload a Visdom JSON file as a new environment
      description: >
        Accepts a Visdom environment-export JSON file via multipart form upload
        and loads it as a new environment named `uploaded_<name>_<id>`. The
        uploaded JSON must be an object containing `jsons` and `reload` keys.
        The new environment is saved to disk (when a persistence path is
        configured) and an `env_update` broadcast is sent. Maximum file size is
        100 MB. Rejected when the server is running in readonly mode.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: >
                    A Visdom environment-export JSON file (object with `jsons`
                    and `reload` keys).
      responses:
        "200":
          description: Environment created from the uploaded file.
          content:
            application/json:
              schema:
                type: object
                required: [success, eid, message]
                properties:
                  success:
                    type: boolean
                  eid:
                    type: string
                    description: ID of the newly created environment.
                  message:
                    type: string
              examples:
                uploaded:
                  value:
                    success: true
                    eid: uploaded_myrun_1a2b3c4d
                    message: "Dashboard loaded successfully as 'uploaded_myrun_1a2b3c4d'"
        "400":
          description: >
            No file uploaded, invalid JSON, not a valid Visdom JSON, or
            authentication required but not provided (when login is enabled).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadErrorResponse"
        "403":
          description: Uploads are disabled because the server is in readonly mode.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadErrorResponse"
        "413":
          description: Uploaded file exceeds the 100 MB size limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadErrorResponse"

  /env/{eid}:
    get:
      operationId: renderEnvironmentPage
      tags: [Environment]
      summary: Render the environment UI page
      description: >
        Returns the Visdom HTML page for the specified environment. This is
        the main web UI entry point for a specific environment.
      parameters:
        - name: eid
          in: path
          required: true
          schema:
            type: string
          description: Environment ID.
      responses:
        "200":
          description: HTML page for the environment.
          content:
            text/html:
              schema:
                type: string
        "400":
          description: Authentication required but not provided (when login is enabled).
    post:
      operationId: loadEnvironment
      tags: [Environment]
      summary: Load environment data to a client socket or create a new environment
      description: >
        If `sid` is provided and matches a subscribed socket, the
        environment's windows and layout are sent to that specific socket.
        If `eid` is provided and does not exist, a new empty environment
        is created and an `env_update` broadcast is sent.
      parameters:
        - name: eid
          in: path
          required: true
          schema:
            type: string
          description: Environment ID (from URL path).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sid:
                  type: string
                  description: >
                    Socket ID of the subscriber to load the environment to.
                eid:
                  type: string
                  description: >
                    Environment ID to create if it does not exist.
      responses:
        "200":
          description: >
            Environment loaded to the specified socket, or new environment
            created. No body returned.
        "400":
          description: Authentication required but not provided (when login is enabled).

  /compare/{eids}:
    get:
      operationId: renderComparePage
      tags: [Environment]
      summary: Render the comparison view for multiple environments
      description: >
        Returns the Visdom HTML page configured for comparing multiple
        environments side by side. Windows with matching titles across
        environments are combined. Plots show traces from each environment
        with prefixed legend names. Images are displayed in a comparison
        grid.
      parameters:
        - name: eids
          in: path
          required: true
          schema:
            type: string
          description: >
            Environment IDs separated by `+` (e.g., `env1+env2+env3`).
      responses:
        "200":
          description: HTML page for environment comparison.
          content:
            text/html:
              schema:
                type: string
        "400":
          description: Authentication required but not provided (when login is enabled).
    post:
      operationId: loadComparisonData
      tags: [Environment]
      summary: Load comparison data for multiple environments to a client socket
      description: >
        Sends comparison window data to the specified subscriber socket.
        Only windows of type `"plot"` or `"image"` with matching, non-empty
        titles across at least two environments are included. Plot traces
        are prefixed with the environment index. Images are shown side by
        side with captioned labels.
      parameters:
        - name: eids
          in: path
          required: true
          schema:
            type: string
          description: >
            Environment IDs separated by `+` (e.g., `env1+env2+env3`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sid]
              properties:
                sid:
                  type: string
                  description: Socket ID of the subscriber to load comparison data to.
      responses:
        "200":
          description: >
            Comparison data sent to the specified socket. No body returned.
        "400":
          description: Authentication required but not provided (when login is enabled).

  /user/{path}:
    get:
      operationId: getUserSettings
      tags: [System]
      summary: Retrieve user settings files
      description: >
        Currently only supports `style.css` as the path parameter. Returns
        the user's custom CSS stylesheet.
      security: []
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
            enum: ["style.css"]
          description: Settings file path. Currently only `"style.css"` is supported.
      responses:
        "200":
          description: User CSS content.
          content:
            text/css:
              schema:
                type: string

  /health:
    get:
      operationId: healthCheck
      tags: [System]
      summary: Health check endpoint
      description: >
        Returns a simple JSON object indicating the server is running.
        This endpoint does not require authentication.
      security: []
      responses:
        "200":
          description: Server is healthy.
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  status:
                    type: string
                    enum: ["ok"]
              examples:
                healthy:
                  value:
                    status: ok
        "400":
          description: Bad request.

  /error/{text}:
    get:
      operationId: triggerError
      tags: [System]
      summary: Test endpoint that raises an error
      description: >
        Raises an exception with the provided text message. Used for
        testing error handling. This endpoint does not require
        authentication.
      security: []
      parameters:
        - name: text
          in: path
          required: true
          schema:
            type: string
          description: Error message text. Defaults to `"test error"` if empty.
      responses:
        "500":
          description: Server error with the specified message (endpoint always raises).

  /:
    get:
      operationId: renderMainPage
      tags: [Authentication]
      summary: Render the main Visdom page or login page
      description: >
        If authentication is disabled or the user is authenticated, renders
        the main Visdom UI (`index.html`). If authentication is enabled
        and the user is not authenticated, renders the login page
        (`login.html`).
      security: []
      responses:
        "200":
          description: HTML page (index.html or login.html).
          content:
            text/html:
              schema:
                type: string
        "400":
          description: Bad request.
    post:
      operationId: login
      tags: [Authentication]
      summary: Authenticate and create a session
      description: >
        Validates the username and password against the server's configured
        credentials. The password is SHA-256 hashed on the server side
        (the client should also pre-hash once before sending). On success,
        sets a secure cookie (`user_password`). On failure, returns 400.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                  description: Username for authentication.
                password:
                  type: string
                  description: >
                    Password string (typically pre-hashed once on the
                    client side with SHA-256, then hashed again on the
                    server).
      responses:
        "200":
          description: >
            Authentication successful. A `user_password` secure cookie is
            set. No body returned.
          headers:
            Set-Cookie:
              schema:
                type: string
              description: Secure session cookie.
        "400":
          description: Invalid credentials.

  /socket:
    get:
      operationId: subscribeSocket
      tags: [Socket Polling]
      summary: WebSocket endpoint for subscribing to visualization updates
      description: >
        WebSocket connection for read-only subscribers. Clients connect via
        the WebSocket protocol (HTTP Upgrade). On connection, the server
        sends a `register` message with the assigned socket ID, readonly
        status, and current environment list. The server then streams
        window updates, close events, environment/tag updates, and layout
        changes. Tag updates use the `tags_update` command with
        `{eid, tags}` data. Clients can send commands: `close`, `save`, `save_all`,
        `delete_env`, `save_layouts`, `forward_to_vis`,
        `layout_item_update`, `pop_embeddings_pane`.


        **Note:** This is a WebSocket endpoint. OpenAPI does not natively
        support WebSocket, so this is documented as a GET for reference.
      responses:
        "200":
          description: Not applicable. This endpoint upgrades to WebSocket (101).
        "101":
          description: >
            Switching Protocols. WebSocket connection established. Server
            sends a JSON register message with `command`, `data` (socket
            ID), `readonly`, and `envList` fields. If authentication is
            enabled and the user is not authenticated, the connection is
            accepted then immediately closed.

  /vis_socket:
    get:
      operationId: visSourceSocket
      tags: [Socket Polling]
      summary: WebSocket endpoint for visualization data sources
      description: >
        WebSocket connection for visualization sources with write access.
        Clients connect via the WebSocket protocol (HTTP Upgrade). On
        connection, the server sends an `alive` message. Sources can
        push visualization data and send commands: `echo`, `close`,
        `save`, `save_all`, `delete_env`, `save_layouts`,
        `forward_to_vis`, `layout_item_update`, `pop_embeddings_pane`.


        **Note:** This is a WebSocket endpoint. OpenAPI does not natively
        support WebSocket, so this is documented as a GET for reference.
      responses:
        "200":
          description: Not applicable. This endpoint upgrades to WebSocket (101).
        "101":
          description: >
            Switching Protocols. WebSocket connection established. Server
            sends a JSON alive message with `{"command": "alive", "data": "vis_alive"}`.
            If authentication is enabled and the user is not authenticated,
            the connection is accepted then immediately closed.

  /socket_wrap:
    get:
      operationId: createSocketWrapper
      tags: [Socket Polling]
      summary: Create a new polling-based subscriber socket
      description: >
        Creates a new subscriber socket wrapper for HTTP polling. Returns
        the socket ID that must be used in subsequent POST requests to
        send/receive messages. This is a fallback for environments that
        do not support WebSocket connections.
      responses:
        "200":
          description: New socket wrapper created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SocketWrapCreateResponse"
        "400":
          description: Authentication required but not provided (when login is enabled).
    post:
      operationId: pollSubscriberSocket
      tags: [Socket Polling]
      summary: Send or query messages on a polling-based subscriber socket
      description: >
        Interact with a polling-based subscriber socket. Use
        `message_type: "query"` to retrieve pending messages, or
        `message_type: "send"` to send a message (command) to the server.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SocketWrapRequest"
      responses:
        "200":
          description: Operation result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SocketWrapResponse"

  /vis_socket_wrap:
    post:
      operationId: pollVisSourceSocket
      tags: [Socket Polling]
      summary: Send or query messages on a polling-based visualization source socket
      description: >
        Interact with a polling-based visualization source socket (write
        access). Use `message_type: "query"` to retrieve pending messages,
        or `message_type: "send"` to send a message. If `sid` is null or
        omitted, a new visualization source socket is created and its ID
        is returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SocketWrapRequest"
      responses:
        "200":
          description: Operation result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SocketWrapResponse"

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: user_password
      description: >
        Session cookie set by the `POST /` login endpoint. Required when
        the server is started with `--enable_login`.

  schemas:

    ExperimentComparisonSection:
      type: object
      description: >
        One section (params, metrics or tags) of an experiment comparison,
        diffed across the compared runs.
      required: [fields, shared, differing, values, groups]
      properties:
        fields:
          type: array
          description: Every field name any compared run has, sorted.
          items:
            type: string
        shared:
          type: object
          additionalProperties: true
          description: >
            The fields every compared run carries with the same value, as
            `{name: value}`.
        differing:
          type: array
          description: >
            The remaining fields — those whose value varies between runs, or
            that some run is missing.
          items:
            type: string
        values:
          type: object
          additionalProperties:
            type: object
            additionalProperties: true
          description: >
            Per-field, per-run values as `{field: {env_id: value}}`. A run that
            never logged the field is omitted from that field's map.
        groups:
          type: object
          description: >
            Per field, the runs clustered by the value they used — the finer
            question "which runs agree?", where `shared`/`differing` answer only
            "do they all?". With three runs on two learning rates, the two that
            match share a group. A field appears in `shared` exactly when its
            groups are a single cluster holding every compared run, so the two
            never disagree. Groups are ordered by first appearance, and a run
            that never logged the field is in no group.
          additionalProperties:
            type: array
            items:
              type: object
              required: [value, env_ids]
              properties:
                value:
                  description: The value these runs share.
                env_ids:
                  type: array
                  description: The runs that used it, in compared order.
                  items:
                    type: string

    Experiment:
      type: object
      description: Experiment metadata attached to an environment.
      properties:
        env_id:
          type: string
          description: Environment the experiment belongs to.
        name:
          type: string
          description: Display name. Defaults to the env_id.
        description:
          type: string
        status:
          type: string
          enum: [running, finished, failed]
          description: Lifecycle state. New experiments start `running`.
        created_at:
          type: number
          description: Unix timestamp when the experiment was created.
        finished_at:
          type: [number, "null"]
          description: Unix timestamp when finished, or `null` while running.
        params:
          type: array
          description: Hyper-parameters, keyed by name.
          items:
            type: object
            properties:
              key:
                type: string
              value: {}
              dtype:
                type: string
                enum: [bool, int, float, str]
                description: Inferred type, so a stored value can be cast back.
        metrics:
          type: array
          description: Metric observations, appended over time.
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: number
              step:
                type: [integer, "null"]
              timestamp:
                type: number
        tags:
          type: array
          description: Free-form key/value labels.
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string

    UploadErrorResponse:
      type: object
      description: Error response returned by the /upload_env endpoint.
      properties:
        success:
          type: boolean
          description: Always `false` for error responses.
        error:
          type: string
          description: Human-readable description of what went wrong.

    CreateWindowRequest:
      type: object
      required: [data]
      description: >
        Request body for creating a new visualization window. The `data`
        array defines the content and type of visualization. The server
        determines the window type from `data[0].type`.
      properties:
        data:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/WindowData"
          description: >
            Array of data objects. For plot types (scatter, line, bar, etc.),
            each element is a Plotly trace object. For visdom-native types
            (image, text, properties, network, embeddings), a single element
            with a `content` field is used.
        layout:
          $ref: "#/components/schemas/PlotlyLayout"
        opts:
          $ref: "#/components/schemas/WindowOptions"
        win:
          type:
            - string
            - "null"
          description: >
            Window ID. If null or omitted, a new unique ID is
            auto-generated.
        eid:
          type:
            - string
            - "null"
          description: >
            Environment ID. Defaults to `"main"` if omitted.

    UpdateWindowRequest:
      type: object
      required: [win]
      description: Request body for updating an existing visualization window.
      properties:
        win:
          type: string
          description: Window ID to update.
        eid:
          type:
            - string
            - "null"
          description: >
            Environment ID. Defaults to `"main"` if omitted.
        data:
          oneOf:
            - type: array
              items:
                $ref: "#/components/schemas/WindowData"
              description: >
                Array of data objects for plot updates.
            - type: object
              description: >
                Object data for embeddings updates.
              properties:
                update_type:
                  type: string
                  enum: [EntitySelected, RegionSelected]
                  description: Type of embeddings update.
                selected:
                  type:
                    - integer
                    - "null"
                  description: >
                    Selected entity index (for EntitySelected) or null.
                points:
                  type: array
                  items:
                    type: array
                    items:
                      type: number
                  description: >
                    Array of [x, y] points (for RegionSelected).
        name:
          type:
            - string
            - "null"
          description: >
            Trace name to update (for scatter/line plots). When specified
            with `delete: true`, deletes that trace.
        append:
          type: boolean
          description: >
            If true, append data to existing traces instead of replacing.
            If the window does not exist and `append` is true, a new
            window is created.
        delete:
          type: boolean
          description: >
            If true, delete the trace specified by `name`.
        updateDir:
          type: string
          enum: [replace, appendRow, prependRow, appendColumn, prependColumn]
          description: >
            Direction for heatmap updates. `replace` overwrites the entire
            heatmap. Other values append or prepend rows/columns.
        opts:
          $ref: "#/components/schemas/WindowOptions"
        layout:
          $ref: "#/components/schemas/PlotlyLayout"
        layout_create:
          allOf:
            - $ref: "#/components/schemas/PlotlyLayout"
          description: >
            Layout to use only if this request has to create the window --
            that is, when `append` is true and `win` does not exist yet. An
            append deliberately sends an empty `layout` so that it never
            restyles a window that is already there, which leaves a
            create-on-append with no layout at all; sending `layout_create`
            lets a client append and create in one call instead of asking
            `/win_exists` first. Ignored when the window already exists, and
            ignored when a non-empty `layout` is also present.

    GetWindowDataRequest:
      type: object
      description: Request to retrieve window or environment data.
      properties:
        eid:
          type:
            - string
            - "null"
          description: >
            Environment ID. Defaults to `"main"` if omitted.
        win:
          type:
            - string
            - "null"
          description: >
            Window ID. If null, returns all windows in the environment.

    SetWindowDataRequest:
      type: object
      required: [data]
      description: Request to overwrite window or environment data.
      properties:
        eid:
          type:
            - string
            - "null"
          description: >
            Environment ID. Defaults to `"main"` if omitted.
        win:
          type:
            - string
            - "null"
          description: >
            Window ID. If null, replaces all windows in the environment.
        data:
          type: string
          description: >
            JSON-encoded string of the window object or the complete
            environment jsons map (when win is null).

    SocketWrapRequest:
      type: object
      description: Request body for socket polling operations.
      properties:
        message_type:
          type: string
          enum: [query, send]
          description: >
            `"query"` to retrieve pending messages; `"send"` to dispatch
            a message.
        sid:
          type:
            - string
            - "null"
          description: >
            Socket ID from a previous create call. If null on
            `/vis_socket_wrap`, creates a new visualization source socket.
        message:
          type: string
          description: >
            JSON-encoded message to send (required when
            `message_type` is `"send"`).

    SocketWrapCreateResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        sid:
          type: string
          description: Socket ID for subsequent polling requests.
      required: [success, sid]

    SocketWrapResponse:
      type: object
      description: >
        Response from a socket polling operation. The exact shape depends
        on the operation.
      properties:
        success:
          type: boolean
        messages:
          type: array
          items:
            type: string
          description: >
            Pending messages (present when `message_type` was `"query"`
            and `success` is true).
        reason:
          type: string
          enum: [closed, no msg, invalid]
          description: >
            Failure reason (present when `success` is false).
        sid:
          type: string
          description: >
            Socket ID (present when a new socket was created).
      required: [success]

    WindowData:
      type: object
      description: >
        A single data element in a visualization request. For Plotly-based
        plot types, this follows the Plotly trace schema. For visdom-native
        types (image, text, properties, network, embeddings, image_history),
        this contains a `content` field with type-specific data.
      properties:
        type:
          type: string
          description: >
            The visualization type. Plotly types: `scatter`, `scatter3d`,
            `scattergl`, `bar`, `histogram`, `box`, `heatmap`, `contour`,
            `surface`. Visdom-native types: `image`, `image_history`,
            `text`, `properties`, `network`, `embeddings`, `custom`.
          enum:
            - scatter
            - scatter3d
            - scattergl
            - bar
            - histogram
            - box
            - heatmap
            - contour
            - surface
            - image
            - image_history
            - text
            - properties
            - network
            - embeddings
            - custom
        content:
          description: >
            Content for visdom-native types. Shape depends on `type`:
            - `image`: `{ "src": "data:image/png;base64,...", "caption": "..." }`
            - `text`: HTML string
            - `properties`: array of property objects
            - `network`: `{ "nodes": [...], "edges": [...] }`
            - `embeddings`: `{ "data": [[x,y], ...], "selected": null, "has_previous": false }`
            - `image_history`: same as `image` content
          oneOf:
            - $ref: "#/components/schemas/ImageContent"
            - type: string
              description: HTML content (for text type).
            - type: array
              items:
                $ref: "#/components/schemas/PropertyItem"
              description: Properties array (for properties type).
            - $ref: "#/components/schemas/NetworkContent"
            - $ref: "#/components/schemas/EmbeddingsContent"
        x:
          type: array
          items:
            type:
              - number
              - "null"
          description: X-axis values (Plotly trace).
        y:
          type: array
          items:
            type:
              - number
              - "null"
          description: Y-axis values (Plotly trace).
        z:
          oneOf:
            - type: array
              items:
                type: number
              description: Z-axis values for 3D scatter.
            - type: array
              items:
                type: array
                items:
                  type: number
              description: 2D array of z values for heatmap/surface/contour.
          description: Z values (3D scatter, heatmap, surface, contour).
        name:
          type: string
          description: Trace name (shown in legend).
        mode:
          type: string
          description: >
            Plotly trace mode (e.g., `"markers"`, `"lines"`,
            `"lines+markers"`, `"markers+text"`).
        text:
          type:
            - array
            - "null"
          items:
            type: string
          description: Text labels for each data point.
        textposition:
          type: string
          description: Position of text labels relative to markers.
        fill:
          type: string
          description: Fill area mode (e.g., `"tonexty"`).
        line:
          type: object
          properties:
            dash:
              type:
                - string
                - "null"
              description: Dash style (e.g., `"solid"`, `"dash"`, `"dot"`).
            color:
              type:
                - string
                - "null"
              description: Line color.
        marker:
          $ref: "#/components/schemas/MarkerProperties"

    MarkerProperties:
      type: object
      description: Plotly marker styling properties.
      properties:
        size:
          type: number
          description: Marker size in pixels.
        symbol:
          type: string
          description: >
            Marker symbol (e.g., `"dot"`, `"cross"`, `"diamond"`).
        color:
          oneOf:
            - type: string
            - type: array
              items:
                type: number
            - type: "null"
          description: Marker color (single color string or array of values).
        line:
          type: object
          properties:
            color:
              type: string
              description: Marker border color.
            width:
              type: number
              description: Marker border width.

    ImageContent:
      type: object
      description: Image data for image and image_history window types.
      required: [src]
      properties:
        src:
          type: string
          description: >
            Base64-encoded image data URI
            (e.g., `"data:image/png;base64,iVBOR..."`).
        caption:
          type:
            - string
            - "null"
          description: Optional caption displayed below the image.

    PropertyItem:
      type: object
      description: A single property in a properties pane.
      required: [type, name, value]
      properties:
        type:
          type: string
          enum: [text, number, button, checkbox, select]
          description: >
            Property input type. Determines how the value is rendered.
        name:
          type: string
          description: Display label for the property.
        value:
          oneOf:
            - type: string
            - type: number
            - type: boolean
          description: >
            Current value. Type depends on `type` field:
            text -> string, number -> string (decimal),
            button -> string (label), checkbox -> boolean,
            select -> integer (zero-based index).
        values:
          type: array
          items:
            type: string
          description: >
            List of possible values (only for `select` type).

    NetworkContent:
      type: object
      description: Network graph data.
      properties:
        nodes:
          type: array
          items:
            type: object
          description: Array of node objects.
        edges:
          type: array
          items:
            type: object
          description: Array of edge objects.

    EmbeddingsContent:
      type: object
      description: Embeddings visualization data (t-SNE 2D points).
      properties:
        data:
          type: array
          items:
            type: array
            items:
              type: number
            minItems: 2
            maxItems: 2
          description: Array of [x, y] coordinates for each entity.
        selected:
          type:
            - integer
            - "null"
          description: Index of the currently selected entity, or null.
        has_previous:
          type: boolean
          description: Whether a previous zoom level can be popped.

    PlotlyLayout:
      type: object
      description: >
        Plotly layout configuration. Supports all standard Plotly layout
        properties. Common properties are listed here.
      properties:
        title:
          type: string
          description: Plot title.
        xaxis:
          $ref: "#/components/schemas/PlotlyAxis"
        yaxis:
          $ref: "#/components/schemas/PlotlyAxis"
        scene:
          type: object
          description: 3D scene configuration (used by 3D plots).
          properties:
            xaxis:
              $ref: "#/components/schemas/PlotlyAxis"
            yaxis:
              $ref: "#/components/schemas/PlotlyAxis"
            zaxis:
              $ref: "#/components/schemas/PlotlyAxis"
        showlegend:
          type: boolean
          description: Whether to show the legend.
        legend:
          type: object
          description: Legend configuration object.
        margin:
          type: object
          properties:
            l:
              type: integer
            r:
              type: integer
            t:
              type: integer
            b:
              type: integer
      additionalProperties: true

    PlotlyAxis:
      type: object
      description: Plotly axis configuration.
      properties:
        title:
          type: string
          description: Axis title.
        type:
          type: string
          enum: ["-", linear, log, date, category]
          description: Axis type.
        autorange:
          type: boolean
        range:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
          description: Fixed axis range [min, max].
        showgrid:
          type: boolean
        zeroline:
          type: boolean
        showline:
          type: boolean
        tickvals:
          type: array
          items: {}
          description: Custom tick positions.
        ticktext:
          type: array
          items:
            type: string
          description: Custom tick labels.
      additionalProperties: true

    WindowOptions:
      type: object
      description: >
        Common window options that apply across visualization types. These
        are stored as top-level properties of the window object.
      properties:
        title:
          type: string
          description: Window title displayed in the pane header.
        width:
          type:
            - integer
            - "null"
          description: Window width in pixels.
        height:
          type:
            - integer
            - "null"
          description: Window height in pixels.
        inflate:
          type: boolean
          default: true
          description: Whether the window content inflates to fill the pane.
        show_slider:
          type: boolean
          default: true
          description: Whether to show the image slider (image_history only).
        caption:
          type:
            - string
            - "null"
          description: Caption text (for image, audio, and video panes).
        jpgquality:
          type: integer
          description: >
            JPEG quality (0-100). If set, images are sent as JPEG
            instead of PNG.
        store_history:
          type: boolean
          description: >
            If true, images are stored as image_history type with a
            slider for browsing history.
        legend:
          type: array
          items:
            type: string
          description: Legend names for plot traces.
        markersymbol:
          type: string
          default: dot
          description: Marker symbol for scatter plots.
        markersize:
          type: number
          default: 10
          description: Marker size for scatter plots.
        markercolor:
          description: >
            Marker colors as numpy array. Shape depends on number of
            traces and labels.
        markerborderwidth:
          type: number
          default: 0.5
          description: Marker border line width.
        dash:
          description: >
            Dash patterns for each trace (e.g., `"solid"`, `"dash"`,
            `"dot"`).
        linecolor:
          description: Line colors for each trace.
        textlabels:
          type:
            - array
            - "null"
          items:
            type: string
          description: Text labels for each point in scatter plots.
        mode:
          type: string
          description: >
            Plotly trace mode override (e.g., `"markers"`, `"lines"`,
            `"lines+markers"`).
        webgl:
          type: boolean
          description: >
            If true, use `scattergl` (WebGL) instead of `scatter`
            (SVG) for better performance with large datasets.
        fillarea:
          type: boolean
          description: If true, fill the area under lines.
        columnnames:
          type: array
          items:
            type: string
          description: Column names for heatmap X axis.
        rownames:
          type: array
          items:
            type: string
          description: Row names for heatmap Y axis.
        colormap:
          type: string
          description: >
            Plotly colorscale name for heatmaps (e.g., `"Viridis"`,
            `"Electric"`).
        directed:
          type: boolean
          default: false
          description: Whether the network graph is directed.
        showEdgeLabels:
          type: string
          enum: [hover, all]
          default: hover
          description: When to show edge labels.
        showVertexLabels:
          type: string
          enum: [hover, all]
          default: hover
          description: When to show vertex labels.
        sample_frequency:
          type: integer
          default: 44100
          description: Audio sample frequency in Hz.
        videowidth:
          type: integer
          description: Video player width.
        videoheight:
          type: integer
          description: Video player height.
        fps:
          type: integer
          default: 25
          description: Frames per second for tensor-based video.
        traceopts:
          type: object
          description: >
            Per-trace Plotly options keyed by trace name under a
            `"plotly"` sub-object.
          properties:
            plotly:
              type: object
              additionalProperties:
                type: object
      additionalProperties: true

    WindowObject:
      type: object
      description: >
        The complete window data structure as stored on the server and sent
        to clients via WebSocket broadcasts.
      required: [command, id, type, content, contentID]
      properties:
        command:
          type: string
          const: window
          description: Always `"window"` for window objects.
        version:
          type: integer
          default: 1
          description: >
            Window version counter. Incremented on each update.
        id:
          type: string
          description: Unique window identifier.
        title:
          type: string
          description: Window title.
        inflate:
          type: boolean
          description: Whether content inflates to fill the pane.
        width:
          type:
            - integer
            - "null"
          description: Window width in pixels.
        height:
          type:
            - integer
            - "null"
          description: Window height in pixels.
        contentID:
          type: string
          description: >
            Random string that changes on every update, used by clients
            to detect changes.
        type:
          type: string
          enum: [plot, image, image_history, image_compare, text, properties, network, embeddings]
          description: Window type.
        content:
          description: >
            Window content. Shape depends on `type`:
            - `plot`: `{ "data": [...traces], "layout": {...} }`
            - `image`: `{ "src": "data:...", "caption": "..." }`
            - `image_history`: array of image content objects
            - `image_compare`: array of image content objects
            - `text`: HTML string
            - `properties`: array of property items
            - `network`: `{ "nodes": [...], "edges": [...] }`
            - `embeddings`: `{ "data": [[x,y],...], "selected": null, "has_previous": false }`
        i:
          type: integer
          description: Position index in the environment layout.
        selected:
          type: integer
          description: Currently selected image index (image_history only).
        show_slider:
          type: boolean
          description: Whether to show the slider (image_history only).
        directed:
          type: boolean
          description: Whether the graph is directed (network only).
        showEdgeLabels:
          type: string
          enum: [hover, all]
          description: Edge label visibility (network only).
        showVertexLabels:
          type: string
          enum: [hover, all]
          description: Vertex label visibility (network only).
        old_content:
          type: array
          description: >
            Stack of previous embeddings data for zoom-out
            (embeddings only).
        has_compare:
          type: boolean
          description: >
            Whether this window is part of an environment comparison
            (set by `/compare`).