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] }