NATS Monitoring API

openapi: 3.1.0
info:
  title: NATS HTTP Accounts Monitoring API
  description: The NATS server exposes a monitoring HTTP endpoint that provides real-time server statistics including connection info, route details, subscription data, JetStream metrics, and health checks for observability and operations.
  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
servers:
- url: http://localhost:8222
  description: Default NATS monitoring endpoint
tags:
- name: Monitoring
  description: Server monitoring and status endpoints
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
  /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
  /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:
    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
    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'
    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
    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