openapi: 3.0.3
info:
  title: Nagios XI REST API
  description: |
    Built-in REST API for Nagios XI, the commercial enterprise distribution of
    Nagios. The API is split into three sections: Objects (read-only backend for
    hosts, services, contacts, host groups, etc.), Config (admin-only writes for
    hosts and services), and System (admin-only commands such as apply
    configuration, scheduled downtime, status). Responses are returned as JSON
    when `pretty=1` or by default. Authentication uses a per-user Nagios XI API
    key passed via the `apikey` query parameter.
  version: v1
  contact:
    name: Nagios Enterprises
    url: https://www.nagios.com/products/nagios-xi/
  license:
    name: Nagios XI Commercial License
    url: https://www.nagios.com/legal/agreements/

servers:
  - url: https://{nagiosXiHost}/nagiosxi/api/v1
    description: Self-hosted Nagios XI instance
    variables:
      nagiosXiHost:
        default: nagios.example.com
        description: Hostname or IP address of the Nagios XI server

security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []

tags:
  - name: Objects
    description: Read-only backend for hosts, services, host groups, contacts, downtime, history, and other monitored objects.
  - name: Config
    description: Admin-only endpoints to add, modify, and delete hosts and services.
  - name: System
    description: Admin-only endpoints to manage Nagios XI subsystems, apply configuration, schedule downtime, and execute commands.

paths:
  /objects/host:
    get:
      tags: [Objects]
      summary: List Host Objects
      operationId: listHostObjects
      parameters:
        - $ref: '#/components/parameters/Pretty'
        - name: host_name
          in: query
          schema: { type: string }
          description: Filter by host name (supports `name-lk=` modifier for substring match).
        - name: records
          in: query
          schema: { type: string, example: '20:10' }
          description: Pagination, format `count` or `count:startingAt`.
        - name: orderby
          in: query
          schema: { type: string, example: 'host_name:a' }
          description: Order by column, `:a` ascending or `:d` descending.
      responses:
        '200':
          description: Host objects.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HostList' }
  /objects/hoststatus:
    get:
      tags: [Objects]
      summary: List Host Statuses
      operationId: listHostStatuses
      parameters:
        - $ref: '#/components/parameters/Pretty'
        - name: host_name
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Host status records.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HostStatusList' }
  /objects/service:
    get:
      tags: [Objects]
      summary: List Service Objects
      operationId: listServiceObjects
      parameters:
        - $ref: '#/components/parameters/Pretty'
        - name: host_name
          in: query
          schema: { type: string }
        - name: service_description
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Service objects.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ServiceList' }
  /objects/servicestatus:
    get:
      tags: [Objects]
      summary: List Service Statuses
      operationId: listServiceStatuses
      parameters:
        - $ref: '#/components/parameters/Pretty'
        - name: host_name
          in: query
          schema: { type: string }
        - name: name
          in: query
          schema: { type: string }
          description: Service description (with optional `-lk` modifier).
      responses:
        '200':
          description: Service status records.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ServiceStatusList' }
  /objects/hostgroup:
    get:
      tags: [Objects]
      summary: List Host Groups
      operationId: listHostGroups
      parameters:
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Host group objects.
  /objects/servicegroup:
    get:
      tags: [Objects]
      summary: List Service Groups
      operationId: listServiceGroups
      parameters:
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Service group objects.
  /objects/contact:
    get:
      tags: [Objects]
      summary: List Contacts
      operationId: listContacts
      parameters:
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Contact objects.
  /objects/contactgroup:
    get:
      tags: [Objects]
      summary: List Contact Groups
      operationId: listContactGroups
      parameters:
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Contact group objects.
  /objects/timeperiod:
    get:
      tags: [Objects]
      summary: List Time Periods
      operationId: listTimePeriods
      parameters:
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Time period objects.
  /objects/command:
    get:
      tags: [Objects]
      summary: List Commands
      operationId: listCommands
      parameters:
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Command objects.
  /objects/downtime:
    get:
      tags: [Objects]
      summary: List Scheduled Downtime
      operationId: listDowntime
      parameters:
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Scheduled downtime records.
  /objects/statehistory:
    get:
      tags: [Objects]
      summary: List State History
      operationId: listStateHistory
      parameters:
        - $ref: '#/components/parameters/Pretty'
        - name: starttime
          in: query
          schema: { type: integer, format: int64 }
          description: Unix timestamp (default 24 hours ago).
        - name: endtime
          in: query
          schema: { type: integer, format: int64 }
          description: Unix timestamp (default now).
      responses:
        '200':
          description: State history records.

  /config/host:
    post:
      tags: [Config]
      summary: Create Or Update Host
      description: Add or update a Nagios XI host definition. Use `force=1` to skip template-required directives and `applyconfig=1` to immediately apply the running configuration.
      operationId: createOrUpdateHost
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema: { $ref: '#/components/schemas/HostInput' }
      responses:
        '200':
          description: Host created or updated.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MutationResult' }
        '400':
          description: Missing required directives.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MutationError' }
    delete:
      tags: [Config]
      summary: Delete Host
      operationId: deleteHost
      parameters:
        - name: host_name
          in: query
          required: true
          schema: { type: string }
        - name: applyconfig
          in: query
          schema: { type: integer, enum: [0, 1] }
      responses:
        '200':
          description: Host removed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MutationResult' }
  /config/service:
    post:
      tags: [Config]
      summary: Create Or Update Service
      operationId: createOrUpdateService
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema: { $ref: '#/components/schemas/ServiceInput' }
      responses:
        '200':
          description: Service created or updated.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MutationResult' }
    delete:
      tags: [Config]
      summary: Delete Service
      operationId: deleteService
      parameters:
        - name: host_name
          in: query
          required: true
          schema: { type: string }
        - name: service_description
          in: query
          required: true
          schema: { type: string }
        - name: applyconfig
          in: query
          schema: { type: integer, enum: [0, 1] }
      responses:
        '200':
          description: Service removed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MutationResult' }

  /system/status:
    get:
      tags: [System]
      summary: Get System Status
      operationId: getSystemStatus
      parameters:
        - $ref: '#/components/parameters/Pretty'
      responses:
        '200':
          description: Current Nagios XI process status.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SystemStatus' }
  /system/applyconfig:
    post:
      tags: [System]
      summary: Apply Configuration
      description: Run Apply Configuration to validate and restart Nagios with any pending object changes.
      operationId: applyConfig
      responses:
        '200':
          description: Apply configuration triggered.
  /system/scheduleddowntime:
    post:
      tags: [System]
      summary: Schedule Downtime
      operationId: scheduleDowntime
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                comment: { type: string }
                start: { type: integer, format: int64, description: 'Unix timestamp.' }
                end: { type: integer, format: int64 }
                'hosts[]':
                  type: array
                  items: { type: string }
                'services[host][]':
                  type: array
                  items: { type: string }
      responses:
        '200':
          description: Downtime scheduled.

components:
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apikey
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
  parameters:
    Pretty:
      name: pretty
      in: query
      schema: { type: integer, enum: [0, 1], default: 0 }
      description: Set to 1 to return human-readable formatted JSON.
  schemas:
    Host:
      type: object
      properties:
        host_object_id: { type: string }
        host_name: { type: string }
        display_name: { type: string }
        address: { type: string }
        check_command: { type: string }
        max_check_attempts: { type: integer }
        check_interval: { type: number }
        retry_interval: { type: number }
        notification_interval: { type: number }
        notification_period: { type: string }
        contacts: { type: string }
        contact_groups: { type: string }
        hostgroups:
          type: array
          items: { type: string }
    HostList:
      type: object
      properties:
        recordcount: { type: integer }
        host:
          type: array
          items: { $ref: '#/components/schemas/Host' }
    HostStatus:
      type: object
      properties:
        host_object_id: { type: string }
        host_name: { type: string }
        current_state:
          type: integer
          enum: [0, 1, 2, 3]
          description: 0=UP, 1=DOWN, 2=UNREACHABLE, 3=UNKNOWN.
        status_update_time: { type: string, format: date-time }
        last_check: { type: string, format: date-time }
        last_state_change: { type: string, format: date-time }
        output: { type: string }
        perfdata: { type: string }
        notifications_enabled: { type: integer, enum: [0, 1] }
        active_checks_enabled: { type: integer, enum: [0, 1] }
        passive_checks_enabled: { type: integer, enum: [0, 1] }
    HostStatusList:
      type: object
      properties:
        recordcount: { type: integer }
        hoststatus:
          type: array
          items: { $ref: '#/components/schemas/HostStatus' }
    Service:
      type: object
      properties:
        service_object_id: { type: string }
        host_name: { type: string }
        service_description: { type: string }
        display_name: { type: string }
        check_command: { type: string }
        max_check_attempts: { type: integer }
        check_interval: { type: number }
        retry_interval: { type: number }
        notification_interval: { type: number }
        check_period: { type: string }
        notification_period: { type: string }
    ServiceList:
      type: object
      properties:
        recordcount: { type: integer }
        service:
          type: array
          items: { $ref: '#/components/schemas/Service' }
    ServiceStatus:
      type: object
      properties:
        service_object_id: { type: string }
        host_name: { type: string }
        service_description: { type: string }
        current_state:
          type: integer
          enum: [0, 1, 2, 3]
          description: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN.
        last_check: { type: string, format: date-time }
        last_state_change: { type: string, format: date-time }
        output: { type: string }
        perfdata: { type: string }
    ServiceStatusList:
      type: object
      properties:
        recordcount: { type: integer }
        servicestatus:
          type: array
          items: { $ref: '#/components/schemas/ServiceStatus' }
    HostInput:
      type: object
      required: [host_name, address]
      properties:
        host_name: { type: string, example: 'web01' }
        address: { type: string, example: '10.0.0.5' }
        use:
          type: string
          example: xiwizard_generic_host
          description: Template to inherit from.
        max_check_attempts: { type: integer }
        check_interval: { type: number }
        retry_interval: { type: number }
        check_period: { type: string }
        notification_interval: { type: number }
        notification_period: { type: string }
        contacts: { type: string }
        contact_groups: { type: string }
        force:
          type: integer
          enum: [0, 1]
          description: When 1, bypass the missing-directive check (rely on template values).
        applyconfig:
          type: integer
          enum: [0, 1]
          description: When 1, apply the configuration immediately after writing.
    ServiceInput:
      type: object
      required: [host_name, service_description]
      properties:
        host_name: { type: string }
        service_description: { type: string }
        use: { type: string, example: xiwizard_website_ping_service }
        check_command: { type: string }
        max_check_attempts: { type: integer }
        check_interval: { type: number }
        retry_interval: { type: number }
        notification_interval: { type: number }
        check_period: { type: string }
        notification_period: { type: string }
        contacts: { type: string }
        contact_groups: { type: string }
        force: { type: integer, enum: [0, 1] }
        applyconfig: { type: integer, enum: [0, 1] }
    MutationResult:
      type: object
      properties:
        success: { type: string, example: 'Removed web01 from the system. Config applied, Nagios Core was restarted.' }
    MutationError:
      type: object
      properties:
        error: { type: string, example: 'Missing required variables' }
        missing:
          type: array
          items: { type: string }
    SystemStatus:
      type: object
      properties:
        instance_id: { type: string }
        instance_name: { type: string }
        status_update_time: { type: string, format: date-time }
        program_start_time: { type: string, format: date-time }
        program_run_time: { type: string }
        is_currently_running: { type: integer, enum: [0, 1] }
        process_id: { type: string }
        daemon_mode: { type: integer, enum: [0, 1] }
        notifications_enabled: { type: integer, enum: [0, 1] }
        active_service_checks_enabled: { type: integer, enum: [0, 1] }
        passive_service_checks_enabled: { type: integer, enum: [0, 1] }
        active_host_checks_enabled: { type: integer, enum: [0, 1] }
        passive_host_checks_enabled: { type: integer, enum: [0, 1] }
        event_handlers_enabled: { type: integer, enum: [0, 1] }
        flap_detection_enabled: { type: integer, enum: [0, 1] }
        process_performance_data: { type: integer, enum: [0, 1] }