openapi: 3.0.3
info:
  title: NATS Monitoring API
  description: >-
    The NATS server exposes a monitoring HTTP endpoint that provides
    real-time information about server status, connections, routes,
    subscriptions, JetStream, and health. This API is available on
    the monitoring port (default 8222) and is used for observability,
    debugging, and integration with monitoring systems like Prometheus.
  version: 2.10.0
  contact:
    name: NATS.io
    url: https://nats.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: NATS Server Monitoring Documentation
  url: https://docs.nats.io/running-a-nats-service/nats_admin/monitoring
servers:
  - url: http://localhost:8222
    description: Default NATS monitoring endpoint
paths:
  /varz:
    get:
      operationId: getServerVariables
      summary: NATS Get server general information
      description: >-
        Returns general information about the server including
        version, uptime, CPU and memory usage, connections,
        message counts, and configuration details.
      parameters:
        - name: subs
          in: query
          description: Include subscription information
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Server general information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Varz'
      tags:
        - Monitoring
  /connz:
    get:
      operationId: getConnections
      summary: NATS Get connection information
      description: >-
        Returns detailed information about current client
        connections to the server including IP, port, subscriptions,
        pending bytes, and message statistics.
      parameters:
        - name: sort
          in: query
          description: Sort connections by field
          schema:
            type: string
            enum:
              - cid
              - start
              - subs
              - pending
              - msgs_to
              - msgs_from
              - bytes_to
              - bytes_from
              - last
              - idle
              - uptime
              - stop
              - reason
            default: cid
        - name: auth
          in: query
          description: Include username
          schema:
            type: boolean
            default: false
        - name: subs
          in: query
          description: Include subscriptions
          schema:
            type: boolean
            default: false
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Number of connections to return
          schema:
            type: integer
            default: 1024
        - name: cid
          in: query
          description: Filter by connection ID
          schema:
            type: integer
        - name: state
          in: query
          description: Filter by connection state
          schema:
            type: string
            enum:
              - open
              - closed
              - any
            default: open
      responses:
        '200':
          description: Connection information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connz'
      tags:
        - Monitoring
  /routez:
    get:
      operationId: getRoutes
      summary: NATS Get route information
      description: >-
        Returns information about active routes between servers
        in a NATS cluster including remote server IDs, addresses,
        and message statistics per route.
      parameters:
        - name: subs
          in: query
          description: Include subscription detail
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Route information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Routez'
      tags:
        - Clustering
  /subsz:
    get:
      operationId: getSubscriptions
      summary: NATS Get subscription information
      description: >-
        Returns information about the internal subscription
        routing data structure including number of subscriptions,
        cache size, inserts, removes, and matches.
      parameters:
        - name: subs
          in: query
          description: Include subscription detail
          schema:
            type: boolean
            default: false
        - name: test
          in: query
          description: Test a subscription subject against the subscription routing data structure
          schema:
            type: string
      responses:
        '200':
          description: Subscription information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subsz'
      tags:
        - Monitoring
  /jsz:
    get:
      operationId: getJetStreamInfo
      summary: NATS Get JetStream information
      description: >-
        Returns information about the JetStream subsystem
        including configuration, resource usage, streams,
        consumers, and cluster state.
      parameters:
        - name: acc
          in: query
          description: Filter by account name
          schema:
            type: string
        - name: accounts
          in: query
          description: Include account-level detail
          schema:
            type: boolean
            default: false
        - name: streams
          in: query
          description: Include stream detail
          schema:
            type: boolean
            default: false
        - name: consumers
          in: query
          description: Include consumer detail
          schema:
            type: boolean
            default: false
        - name: config
          in: query
          description: Include configuration detail
          schema:
            type: boolean
            default: false
        - name: leader-only
          in: query
          description: Only return information from the leader
          schema:
            type: boolean
            default: false
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Number of results to return
          schema:
            type: integer
            default: 1024
      responses:
        '200':
          description: JetStream information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Jsz'
      tags:
        - JetStream
  /healthz:
    get:
      operationId: getHealth
      summary: NATS Get server health status
      description: >-
        Returns the health status of the server. Returns 200 OK
        when the server is healthy and ready to accept connections.
        Used for health checks in container orchestration and
        load balancer configurations.
      parameters:
        - name: js-enabled-only
          in: query
          description: Only check JetStream health
          schema:
            type: boolean
            default: false
        - name: js-server-only
          in: query
          description: Only check if JetStream server is running
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Server is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Healthz'
        '503':
          description: Server is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Healthz'
      tags:
        - Health
  /gatewayz:
    get:
      operationId: getGateways
      summary: NATS Get gateway information
      description: >-
        Returns information about configured gateways between
        NATS super-clusters including remote gateway connections
        and message statistics.
      parameters:
        - name: accs
          in: query
          description: Include account information
          schema:
            type: boolean
            default: false
        - name: gw_name
          in: query
          description: Filter by gateway name
          schema:
            type: string
      responses:
        '200':
          description: Gateway information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gatewayz'
      tags:
        - Clustering
  /leafz:
    get:
      operationId: getLeafNodes
      summary: NATS Get leaf node information
      description: >-
        Returns information about leaf node connections
        including remote address, account, and message statistics.
      parameters:
        - name: subs
          in: query
          description: Include subscription detail
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Leaf node information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Leafz'
      tags:
        - Clustering
  /accountz:
    get:
      operationId: getAccounts
      summary: NATS Get account information
      description: >-
        Returns information about server accounts including
        connection counts, leaf node counts, and subscription counts.
      parameters:
        - name: acc
          in: query
          description: Filter by account name
          schema:
            type: string
      responses:
        '200':
          description: Account information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Accountz'
      tags:
        - Monitoring
components:
  schemas:
    Varz:
      type: object
      properties:
        server_id:
          type: string
          description: Unique server ID
        server_name:
          type: string
          description: Server name
        version:
          type: string
          description: NATS server version
        proto:
          type: integer
          description: Protocol version
        go:
          type: string
          description: Go version used to build the server
        host:
          type: string
          description: Server host
        port:
          type: integer
          description: Client port
        max_connections:
          type: integer
          description: Maximum allowed connections
        ping_interval:
          type: integer
          description: Ping interval in nanoseconds
        ping_max:
          type: integer
          description: Maximum outstanding pings
        http_host:
          type: string
          description: HTTP monitoring host
        http_port:
          type: integer
          description: HTTP monitoring port
        http_base_path:
          type: string
          description: HTTP base path
        max_control_line:
          type: integer
          description: Maximum control line size
        max_payload:
          type: integer
          description: Maximum payload size
        max_pending:
          type: integer
          description: Maximum pending bytes per connection
        cluster:
          type: object
          properties:
            name:
              type: string
            addr:
              type: string
            cluster_port:
              type: integer
            auth_timeout:
              type: integer
        gateway:
          type: object
          properties:
            name:
              type: string
            host:
              type: string
            port:
              type: integer
        leaf:
          type: object
          properties:
            host:
              type: string
            port:
              type: integer
            auth_timeout:
              type: integer
        jetstream:
          type: object
          properties:
            config:
              type: object
              properties:
                max_memory:
                  type: integer
                max_storage:
                  type: integer
                store_dir:
                  type: string
            stats:
              type: object
              properties:
                memory:
                  type: integer
                storage:
                  type: integer
                reserved_memory:
                  type: integer
                reserved_storage:
                  type: integer
                accounts:
                  type: integer
                ha_assets:
                  type: integer
                api:
                  type: object
                  properties:
                    total:
                      type: integer
                    errors:
                      type: integer
        tls_required:
          type: boolean
          description: Whether TLS is required
        tls_verify:
          type: boolean
          description: Whether TLS client verification is enabled
        now:
          type: string
          format: date-time
          description: Current server time
        uptime:
          type: string
          description: Server uptime duration
        mem:
          type: integer
          description: Server memory usage in bytes
        cores:
          type: integer
          description: Number of CPU cores
        cpu:
          type: number
          description: CPU usage percentage
        connections:
          type: integer
          description: Current number of connections
        total_connections:
          type: integer
          description: Total connections since start
        routes:
          type: integer
          description: Number of active routes
        remotes:
          type: integer
          description: Number of remote connections
        leafnodes:
          type: integer
          description: Number of leaf node connections
        in_msgs:
          type: integer
          description: Total inbound messages
        out_msgs:
          type: integer
          description: Total outbound messages
        in_bytes:
          type: integer
          description: Total inbound bytes
        out_bytes:
          type: integer
          description: Total outbound bytes
        slow_consumers:
          type: integer
          description: Number of slow consumers
        subscriptions:
          type: integer
          description: Number of subscriptions
        config_load_time:
          type: string
          format: date-time
          description: Time of last config load
        system_account:
          type: string
          description: System account name
    Connz:
      type: object
      properties:
        server_id:
          type: string
        now:
          type: string
          format: date-time
        num_connections:
          type: integer
          description: Total current connections
        total:
          type: integer
          description: Total connections matching filter
        offset:
          type: integer
          description: Pagination offset
        limit:
          type: integer
          description: Pagination limit
        connections:
          type: array
          items:
            $ref: '#/components/schemas/ConnectionInfo'
    ConnectionInfo:
      type: object
      properties:
        cid:
          type: integer
          description: Connection ID
        kind:
          type: string
          description: Connection kind
        type:
          type: string
          description: Connection type
        ip:
          type: string
          description: Client IP address
        port:
          type: integer
          description: Client port
        start:
          type: string
          format: date-time
          description: Connection start time
        last_activity:
          type: string
          format: date-time
          description: Last activity time
        rtt:
          type: string
          description: Round trip time
        uptime:
          type: string
          description: Connection uptime
        idle:
          type: string
          description: Idle duration
        pending_bytes:
          type: integer
          description: Pending bytes
        in_msgs:
          type: integer
          description: Messages received
        out_msgs:
          type: integer
          description: Messages sent
        in_bytes:
          type: integer
          description: Bytes received
        out_bytes:
          type: integer
          description: Bytes sent
        subscriptions:
          type: integer
          description: Number of subscriptions
        name:
          type: string
          description: Client name
        lang:
          type: string
          description: Client language
        version:
          type: string
          description: Client version
        account:
          type: string
          description: Account name
    Routez:
      type: object
      properties:
        server_id:
          type: string
        now:
          type: string
          format: date-time
        num_routes:
          type: integer
          description: Number of active routes
        routes:
          type: array
          items:
            type: object
            properties:
              rid:
                type: integer
                description: Route ID
              remote_id:
                type: string
                description: Remote server ID
              remote_name:
                type: string
                description: Remote server name
              did_solicit:
                type: boolean
                description: Whether this server initiated the route
              is_configured:
                type: boolean
                description: Whether route is explicitly configured
              ip:
                type: string
                description: Remote IP
              port:
                type: integer
                description: Remote port
              pending_size:
                type: integer
                description: Pending bytes
              in_msgs:
                type: integer
              out_msgs:
                type: integer
              in_bytes:
                type: integer
              out_bytes:
                type: integer
              subscriptions:
                type: integer
    Subsz:
      type: object
      properties:
        num_subscriptions:
          type: integer
          description: Total number of subscriptions
        num_cache:
          type: integer
          description: Number of cached entries
        num_inserts:
          type: integer
          description: Number of subscription inserts
        num_removes:
          type: integer
          description: Number of subscription removes
        num_matches:
          type: integer
          description: Number of subscription matches
        cache_hit_rate:
          type: number
          description: Cache hit rate percentage
        max_fanout:
          type: integer
          description: Maximum fanout
        avg_fanout:
          type: number
          description: Average fanout
    Jsz:
      type: object
      properties:
        server_id:
          type: string
        now:
          type: string
          format: date-time
        config:
          type: object
          properties:
            max_memory:
              type: integer
            max_storage:
              type: integer
            store_dir:
              type: string
            sync_interval:
              type: integer
        memory:
          type: integer
          description: Current memory usage
        storage:
          type: integer
          description: Current storage usage
        reserved_memory:
          type: integer
        reserved_storage:
          type: integer
        accounts:
          type: integer
          description: Number of JetStream accounts
        ha_assets:
          type: integer
          description: Number of HA assets
        api:
          type: object
          properties:
            total:
              type: integer
              description: Total API requests
            errors:
              type: integer
              description: Total API errors
        streams:
          type: integer
          description: Total number of streams
        consumers:
          type: integer
          description: Total number of consumers
        messages:
          type: integer
          description: Total number of stored messages
        bytes:
          type: integer
          description: Total stored bytes
    Healthz:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
            - error
            - unavailable
          description: Server health status
        error:
          type: string
          description: Error message if unhealthy
    Gatewayz:
      type: object
      properties:
        server_id:
          type: string
        now:
          type: string
          format: date-time
        name:
          type: string
          description: Gateway cluster name
        host:
          type: string
        port:
          type: integer
        outbound_gateways:
          type: object
          additionalProperties:
            type: object
            properties:
              configured:
                type: boolean
              connection:
                type: object
                properties:
                  cid:
                    type: integer
                  ip:
                    type: string
                  port:
                    type: integer
                  start:
                    type: string
                    format: date-time
                  uptime:
                    type: string
                  in_msgs:
                    type: integer
                  out_msgs:
                    type: integer
                  in_bytes:
                    type: integer
                  out_bytes:
                    type: integer
        inbound_gateways:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                configured:
                  type: boolean
                connection:
                  type: object
                  properties:
                    cid:
                      type: integer
                    ip:
                      type: string
                    port:
                      type: integer
                    start:
                      type: string
                      format: date-time
                    uptime:
                      type: string
                    in_msgs:
                      type: integer
                    out_msgs:
                      type: integer
                    in_bytes:
                      type: integer
                    out_bytes:
                      type: integer
    Leafz:
      type: object
      properties:
        server_id:
          type: string
        now:
          type: string
          format: date-time
        leafnodes:
          type: integer
          description: Number of leaf node connections
        leafs:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Leaf node name
              is_spoke:
                type: boolean
                description: Whether this is a spoke connection
              account:
                type: string
                description: Account name
              ip:
                type: string
              port:
                type: integer
              rtt:
                type: string
              in_msgs:
                type: integer
              out_msgs:
                type: integer
              in_bytes:
                type: integer
              out_bytes:
                type: integer
              subscriptions:
                type: integer
    Accountz:
      type: object
      properties:
        server_id:
          type: string
        now:
          type: string
          format: date-time
        system_account:
          type: string
        accounts:
          type: array
          items:
            type: string
        account_detail:
          type: object
          properties:
            account_name:
              type: string
            update_time:
              type: string
              format: date-time
            is_system:
              type: boolean
            expired:
              type: boolean
            complete:
              type: boolean
            jetstream_enabled:
              type: boolean
            leafnode_connections:
              type: integer
            client_connections:
              type: integer
            subscriptions:
              type: integer
tags:
  - name: Clustering
    description: Cluster, gateway, and leaf node endpoints
  - name: Health
    description: Health check endpoints
  - name: JetStream
    description: JetStream subsystem monitoring
  - name: Monitoring
    description: Server monitoring and status endpoints