Skip to content

API

Observium includes a structured REST/JSON-based API designed to facilitate access to data held in Observium's MySQL database. An additional graphing API is available to generate graphs from Observium's RRDtool-based metrics.

Active Development

The API is currently in active development. We're still creating its specification and deciding what should be included and what features will be added. If you'd like to be involved in this process, please join our IRC channel where most development discussion takes place.

Subscription Feature

This is a feature which is currently only included in the Subscription Edition of Observium.

Enabling

The API is enabled by adding the following configuration option to config.php :

Text Only
1
$config['api']['enable']                        = TRUE;

Authentication

The API supports:

  • HTTP basic authentication to an existing Observium user (LDAP, RADIUS, MySQL auth backends)
  • API token authentication (Bearer token, and optionally X-API-Token or query token if enabled)

Authentication is simple, for example:

Text Only
1
curl -u <username>:<password> http://observium.domain.com/api/v0/devices/

Bearer token example:

Text Only
1
curl -H "Authorization: Bearer <api_token>" http://observium.domain.com/api/v0/devices/

API tokens are managed from Settings → API Tokens by users with level 7 or higher. Tokens inherit the permissions of the associated user account. Bearer tokens are the recommended token transport; X-API-Token and query-string tokens are disabled by default and must be explicitly enabled in config.php.

Basic Operation

The API has the basic URL structure of /api/<version>/<entity>/<entity_id>/<query>. Both the Entity ID and Query are optional. The query format matches the same as that used by the Web UI, so many of the same options and filters can be used.

For example:

To request a list of all devices

Text Only
1
GET /api/v0/devices/

To request a data array for device with the id 1

Text Only
1
GET /api/v0/devices/1/

Some entity types allow text-based ids, for example to request a data array for the device test.company.com:

Text Only
1
GET /api/v0/devices/test.company.com/

Using the query options is simple too, for example to request all devices with the os ios:

Text Only
1
GET /api/v0/devices/?os=ios

The output from this query would look like this :

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "status": "ok",
  "count": 2,
  "devices": {
    "277": {
      "device_id": "277",
      "hostname": "router-1.company.com",
      "sysObjectID": ".1.3.6.1.4.1.9.1.620",
      "sysDescr": "Cisco IOS Software, 1841 Software (C1841-IPBASE-M), Version 15.0(1)M4, RELEASE SOFTWARE (fc1)\r\nTechnical Support: http://www.cisco.com/techsupport\r\nCopyright 
(c) 1986-2010 by Cisco Systems, Inc.\r\nCompiled Thu 28-Oct-10 15:40 by prod_rel_team",
      "version": "15.0(1)M4",
      "hardware": "CISCO1841",
      "features": "IPBASE",
      "os": "ios",
      ...
      <most device data removed for brevity>
    },
    "278": {
      "device_id": "278",
      "hostname": "router-b.company.com",
      "sysObjectID": ".1.3.6.1.4.1.9.1.620",
      "sysDescr": "Cisco IOS Software, 1841 Software (C1841-IPBASE-M), Version 15.0(1)M4, RELEASE SOFTWARE (fc1)\r\nTechnical Support: http://www.cisco.com/techsupport\r\nCopyright 
(c) 1986-2010 by Cisco Systems, Inc.\r\nCompiled Thu 28-Oct-10 15:40 by prod_rel_team",
      "version": "15.0(1)M4",
      "hardware": "CISCO1841",
      "features": "IPBASE",
      "os": "ios",
      ...
      <most device data removed for brevity>
    }
  }
}

GET Endpoints

GET endpoints are used to retrieve information from Observium.

Endpoint Description Options
/alerts/ /alerts/<alert_id> Fetch permitted alerts device_id, status (failed, ok, delayed, suppressed, all), entity_type, entity_id, alert_test_id
/alert_checks/ /alert_checks/<alert_check_id> Fetch permitted alert checks
/alert_log/ Fetch Alert Log entries log_type, alert_test_id, device_id, entity_type, entity_id, message, timestamp_from, timestamp_to, expand_entities, cache_entities
/address/ Fetch IPv4 or IPv6 interface addresses af (ipv4, ipv6), device_id, device, port_id, port, port_name, interface, type, vrf_id, vrf, network, address, ipv4_address, ipv6_address
/bills/ /bills/<bill_id> Fetch Bills. Disabled by default while the bills API is pending rewrite.
/counters/ /counters/<counter_id> Fetch Counters group_id, device_id, counter_id, entity_id (measured entity), entity_type (measured entity type), entity_state (measured entity state), counter_class, counter_descr, counter_event
/devices/ /devices/<device_id> /devices/<hostname> Fetch Devices group, group_id, device, device_id, hostname, sysname, location, location_text, os, version, hardware, vendor, features, type, status, ignore, disabled, snmpable, graph, address, ipv4_address, ipv6_address, fields, humanize, nokeys
/entity/<entity_type>/<entity_id>/ Fetch Single Entity
/groups/ /groups/<group_id> Fetch Groups entity_type, group_name, group_descr, include_members
/inventory/ /inventory/<entPhysical_id> Fetch entPhysical device_id, os, entPhysicalModelName, entPhysicalSerialNum, entPhysicalDescr, entPhysicalClass, deleted (0/1)
/mempools/ /mempools/<mempool_id> Fetch Mempools group_id, device_id, mempool_descr
/neighbours/ /neighbours/<neighbour_id> Fetch Neighbours device_id, device_b, port_id, port_b, protocol, platform, version, active, remote_port_id
/ports/ /ports/<port_id> Fetch Ports location, device_id, device_group, group, port_id, disable, deleted, ignore, ifSpeed, ifType, ifDuplex, ifVlan, hostname, ifAlias, ifDescr, label, port_label, mac, ifPhysAddress, port_descr_type, errors, alerted, state, fields, humanize
/printersupplies/ /printersupplies/<supply_id> Fetch Printer Supplies group_id, device_id, supply_type, supply_colour, supply_descr
/probes/ /probes/<probe_id> Fetch Probes group_id, device_id, probe_type, probe_descr, sort
/processors/ /processors/<processor_id> Fetch Processors group_id, device_id, processor_descr
/sensors/ /sensors/<sensor_id> Fetch Sensors metric, group, group_id, device_id, entity_id, entity_type, sensor_descr, sensor_type, id, event (ok, alert, warn, ignore)
/status/ /status/<status_id> Fetch Status group_id, device_id, id, class, event (ok, alert, warn, ignore)
/storage/ /storage/<storage_id> Fetch Storage group_id, device_id, storage_descr
/vlans/ /vlans/<vlan> Fetch VLAN summary data
/maintenance/ /maintenance/<maint_id> Fetch Scheduled Maintenance windows active, ended, upcoming, include_associations

The /entity/ GET endpoint is provided as a generic method to retrieve any entity's database entry. This can be used to fetch any single entity entry, for example /entity/port/2342 would fetch the entry for a port with the port_id of 2342.

Field Filtering

Some endpoints allow filtering the results by field, for example by returning only the port_id and port_label fields for a /ports/ query. This can provide much better performance for large queries.

Filtering works by supplying a comma-separated list of fields via the fields parameter.

Common Parameters

Some parameters are common across multiple endpoints:

Option Description
pagesize Enable pagination and set the maximum number of entries returned for the current page. Common paginated endpoints cap this at 50,000 entries.
pageno Select the page number when pagesize is used. Defaults to 1.
debug Include query/debug information on endpoints that support API debug output.
raw Return raw database rows on endpoints that otherwise humanize or format entries.
humanize Add or enable human-readable fields on endpoints that support humanized output.
fields Restrict returned fields on endpoints that support field filtering, currently most useful for /devices/ and /ports/.

Pagination

Some endpoints allow pagination of returned results using the pagesize and pageno parameters. Paginated responses include the total matching row count in count, the requested pagesize and pageno, and countpage containing the number of entries returned on the current page.

Note that database content may change between API queries, so page boundaries can shift on very active systems.

Errors and Permissions

Error responses include status: "failed" with a human-readable message.

Single-object endpoints generally return 404 both when the object does not exist and when the authenticated user is not permitted to read it. This avoids leaking the existence of devices, entities, alerts, or alert checks outside the user's permissions.

Address Endpoint

GET /api/v0/address/ returns discovered interface IP addresses from the IPv4 or IPv6 address tables.

The af parameter selects the address family. Use ipv4 or ipv6. If af is omitted, IPv4 is used by default unless address contains an IPv6 address or ipv6_address is supplied.

Supported filters:

Option Description
af Address family selector. Use ipv4 or ipv6.
device_id Filter by device ID.
device Filter by device ID or hostname. Comma-separated values are accepted.
port_id Filter by port ID.
port, port_name, interface Filter by port label using prefix matching.
type Filter by address type, for example unicast.
vrf_id Filter by VRF ID.
vrf Filter by VRF name.
network Filter by network/CIDR.
address, ipv4_address, ipv6_address Filter by address or address/CIDR. Prefix length is ignored for address matching.

Response fields include status, count, and addresses. When pagination is used, pagesize, pageno, and countpage are also returned. Address rows are returned from the matching address and network tables, excluding binary address fields.

Example:

Bash
1
curl -u user:password "https://observium.example/api/v0/address/?af=ipv6&device_id=42"

Alert Log Endpoint

GET /api/v0/alert_log/ returns alert log entries in reverse event order. The endpoint always paginates results and caps pagesize at 50000.

Supported filters:

Option Description
log_type Filter by alert log type, for example FAIL, OK, ALERT_NOTIFY, or RECOVER_NOTIFY.
alert_test_id Filter by alert checker ID.
device_id Filter by device ID.
entity_type, entity_id Filter by alert entity.
message Filter by log message using partial matching.
timestamp_from, timestamp_to Filter by timestamp range.
expand_entities Add hostname and entity_name to returned entries.
cache_entities Include an entity_cache object for returned entries.

Example:

Bash
1
curl -u user:password "https://observium.example/api/v0/alert_log/?device_id=42&log_type=FAIL"

Groups Endpoint

GET /api/v0/groups/ returns permitted groups. GET /api/v0/groups/<group_id>/ returns a single group.

Supported filters:

Option Description
entity_type Filter by grouped entity type, for example device, port, or sensor.
group_name Filter by group name using partial matching.
group_descr Filter by group description using partial matching.
include_members Set to TRUE to include matching group members.

VLANs Endpoint

GET /api/v0/vlans/ returns a VLAN summary grouped by VLAN ID. GET /api/v0/vlans/<vlan>/ returns devices, names, tagged ports, and untagged ports for the requested VLAN.

The VLAN API requires a user with level 7 or higher.

Devices

Fetching Devices

GET /api/v0/devices/ returns permitted devices. GET /api/v0/devices/<device_id>/ and GET /api/v0/devices/<hostname>/ return one device.

Supported filters and output controls:

Option Description
group, group_id Filter by device group.
device, device_id Filter by device ID.
hostname, sysname, sysContact, sysDescr, serial, purpose Filter text fields using partial matching.
location Filter by exact device location.
location_text Filter location using partial matching.
location_lat, location_lon, location_country, location_state, location_county, location_city Filter geocoded location fields when geocoding is enabled.
os, version, hardware, vendor, features, type, status, status_type, distro, ip, ignore, disabled, snmpable Filter by device fields.
snmp_community, snmp_context, snmp_transport, snmp_port, snmp_maxrep, snmp_version Filter by SNMP configuration fields.
poller, poller_id Filter by poller name or poller ID.
graph Return devices with the specified enabled graph.
address, ipv4_address, ipv6_address Filter devices by IP address or network.
fields Return only the requested comma-separated fields.
humanize Add humanized device fields.
nokeys Set to 1 to return devices as an array instead of keyed by device ID.

Adding a Device

Adding devices is achieved by using the POST method on the /devices/ endpoint. This endpoint uses the same fields as used by the Web UI form. The endpoint will return a JSON array containing the device's id if it's successfully created.

This operation requires a user with level 9 or higher.

At its most basic you need to provide a hostname for the device to be added. If the device can be reached via SNMP using one of the community strings in Observium's configuration, this should be sufficient.

For example:

Text Only
1
2
3
root@srv:/home/observium/dev# curl -u user:pass http://localhost/api/v0/devices/ -H "Content-Type: application/json" -X POST -d '{"hostname":"localhost"}'
{"status":"ok","device_id":1}
root@srv:/home/observium/dev#

More complex scenarios may require additional arguments from the table below.

Option Description
hostname Resolvable hostname or IP address
poller_id Distributed poller ID (available only for Enterprise Edition)
ping_skip Skip check device is Pingable: on (default) or off
snmp_version SNMP version in use: v1, v2c (default) or v3
snmp_port SNMP port (default: 161)
snmp_timeout SNMP timeout (default: 1s)
snmp_retries SNMP retries (default: 5)
snmp_community SNMP community for use with SNMP v1 and v2c
snmp_authlevel SNMP v3 Auth Level (noAuthNoPriv / authNoPriv / authPriv)
snmp_authname SNMP v3 Auth Username
snmp_authpass SNMP v3 Auth Password
snmp_authalgo SNMP v3 Auth Algorithm (md5 / sha / sha-224 / sha-256 / sha-384 / sha-512)
snmp_cryptopass SNMP v3 Encryption Password
snmp_cryptoalgo SNMP v3 Encryption Algorithm (des / aes / aes-192 / aes-192-c / aes-256 / aes-256-c)
snmp_maxrep SNMP Maximum Repetition (default: Empty, set 0 for disable)
snmp_context SNMP Context (default: Empty)

Deleting a device

Deleting devices is performed using the DELETE verb on the /devices/ endpoint with the device_id as the final path element.

This operation requires a user with level 9 or higher. RRD data is deleted by default; set delete_rrd=0 to keep RRD data.

For example:

Text Only
1
2
curl -u user:pass http://observium/api/v0/devices/491/ -X DELETE
{"status":"ok","message":"Device deleted","device_id":"491"}

Changing a device

Devices can have some attributes changed by using a PUT method on the /devices/ endpoint.

This operation requires a user with level 7 or write permission for the device.

Option Description
poller_id Move the device to another poller ID.
syscontact Override or unset sysContact. Use "null" or blank to unset.
syslocation Override or unset sysLocation. Use "null" or blank to unset.
type Override or unset the device type. Use "null" or blank to unset.
ping_skip Skip ICMP reachability checks (0 or 1).
disable_notify Disable notifications for the device (0 or 1).
ignore Ignores the device for alerting ( 0 or 1)
ignore_until Ignores the device until the specified time in the format Y-m-d H:i:s, eg 2017-05-13 12:34:20. "null" or blank unsets.
disabled Disables polling the device ( 0 or 1)
force_discovery Force rediscovery (0 or 1).
purpose Changes/unsets the Purpose/Description of the device. "null" or blank unsets.
snmp_version SNMP version.
snmp_transport SNMP transport.
snmp_port SNMP port.
snmp_timeout SNMP timeout.
snmp_retries SNMP retries.
snmp_maxrep SNMP maximum repetitions.
snmp_context SNMP context.
snmp_community SNMP community for SNMP v1/v2c.
snmp_authlevel SNMP v3 authentication level.
snmp_authalgo SNMP v3 authentication algorithm.
snmp_authname SNMP v3 authentication username.
snmp_authpass SNMP v3 authentication password.
snmp_cryptoalgo SNMP v3 encryption algorithm.
snmp_cryptopass SNMP v3 encryption password.
snmpable Override SNMPable OIDs. Use "null" or blank to unset.
reset_geolocation Reset stored geolocation when true.
location_manual, coordinates Set manual coordinates. Use "null" for location_manual to unset.
Text Only
1
2
3
root@omega:~# curl -u user:password -X PUT http://observium/api/v0/devices/47/ -H "Content-Type: application/json" -d '{"disabled":"1"}'
{"status":"updated","message":"Device updated","device_id":"47","updated":["disabled"]}
root@omega:~#

Alert Entries

Ignoring an alert entry

Alerts can have their ignore_until_ok and ignore_until attributes set by using the PUT method on the /alerts/ endpoint.

For example, this would set the alert to be ignored until it was next found to be ok and also ignored until 12:34:20 on 13th May 2017:

Text Only
1
2
3
root@omega:~# curl -u user:password -X PUT http://observium/api/v0/alerts/48467/ -H "Content-Type: application/json" -d '{"ignore_until_ok":"1", "ignore_until":"2017-05-13 12:34:20"}'
{"status":"updated","message":"Alert 48467 updated."}
root@omega:~#
Option Description
ignore_until_ok Ignores the alert until it is OK. (0 or 1)
ignore_until Ignores the alert until the time specified in the format Y-m-d H:i:s, eg 2017-05-13 12:34:20

Alert Checkers

Fetching a single alert checker

To fetch a single checker by id:

Text Only
1
2
3
root@omega:~# curl -u user:password http://observium/api/v0/alert_checks/12/
{"status":"ok","alert_check":{"alert_test_id":"12", ...}}
root@omega:~#

Enabling/Disabling an alert checker

Alert checkers can be enabled or disabled by using the PUT method on the /alert_checks/ endpoint.

Disabling a checker sets enable=0 and removes existing active entries for that checker from alert_table. Enabling a checker sets enable=1 and regenerates entries.

This operation requires a user with level 9 or higher.

For example, disable checker 12:

Text Only
1
2
3
root@omega:~# curl -u user:password -X PUT http://observium/api/v0/alert_checks/12/ -H "Content-Type: application/json" -d '{"enable":"0"}'
{"status":"updated","message":"Alert checker 12 updated."}
root@omega:~#

Enable checker 12 again:

Text Only
1
2
3
root@omega:~# curl -u user:password -X PUT http://observium/api/v0/alert_checks/12/ -H "Content-Type: application/json" -d '{"enable":"1"}'
{"status":"updated","message":"Alert checker 12 updated."}
root@omega:~#
Option Description
enable Enable or disable the alert checker (0 or 1)
enabled Alias of enable (0 or 1)

Scheduled Maintenance API

Scheduled maintenance windows can be managed via the /maintenance/ API endpoints.

Write operations require a user with level 8 or higher.

GET Endpoints

  • GET /api/v0/maintenance/
  • GET /api/v0/maintenance/<maint_id>/
  • GET /api/v0/maintenance/<maint_id>/associations/

Optional filters for GET /maintenance/:

  • active=1 — windows active right now
  • ended=1 — windows that already ended
  • upcoming=1 — windows with start time in the future
  • include_associations=1 — include associated entities in single-window response

Example:

Text Only
1
curl -u user:password http://observium/api/v0/maintenance/?active=1

Create a Maintenance Window

POST /api/v0/maintenance/

Accepted fields:

  • maint_name (required)
  • maint_descr
  • maint_global (0 or 1)
  • maint_start / maint_end (Unix timestamp or date string)
  • maint_time_from / maint_time_to (aliases for start/end date strings)

Validation rules:

  • start and end must be valid datetimes
  • end must be after start

Example:

Text Only
1
2
3
curl -u user:password -X POST http://observium/api/v0/maintenance/ \
  -H "Content-Type: application/json" \
  -d '{"maint_name":"DC Core Upgrade","maint_descr":"Planned maintenance","maint_global":"0","maint_time_from":"2026-03-01 01:00:00","maint_time_to":"2026-03-01 03:00:00"}'

Update a Maintenance Window

PUT /api/v0/maintenance/<maint_id>/

Updatable fields:

  • maint_name
  • maint_descr
  • maint_global
  • maint_start + maint_end (must be provided together if updating period)
  • maint_time_from + maint_time_to (alias pair)

If no effective changes are made, response status is not_updated.

Example:

Text Only
1
2
3
curl -u user:password -X PUT http://observium/api/v0/maintenance/12/ \
  -H "Content-Type: application/json" \
  -d '{"maint_descr":"Extended maintenance scope"}'

Delete a Maintenance Window

DELETE /api/v0/maintenance/<maint_id>/

Deleting a window also removes linked associations.

Example:

Text Only
1
curl -u user:password -X DELETE http://observium/api/v0/maintenance/12/

Manage Associations

Associations endpoint:

  • POST /api/v0/maintenance/<maint_id>/associations/
  • DELETE /api/v0/maintenance/<maint_id>/associations/

Accepted fields:

  • entity_type (group, device, alert_checker)
  • entity_id (single id or array)
  • entity_ids (array alias)

Association operations are idempotent:

  • adding an existing association returns it under already_exists
  • deleting a missing association returns it under already_removed

Add association example:

Text Only
1
2
3
curl -u user:password -X POST http://observium/api/v0/maintenance/12/associations/ \
  -H "Content-Type: application/json" \
  -d '{"entity_type":"device","entity_ids":[101,102]}'

Remove association example:

Text Only
1
2
3
curl -u user:password -X DELETE http://observium/api/v0/maintenance/12/associations/ \
  -H "Content-Type: application/json" \
  -d '{"entity_type":"device","entity_ids":[101,102]}'