SNMP Data Collection Config REST API (v2)

You can manage SNMP data collection over REST. The same surface is used by the Admin → Manage SNMP Data Collection Config page; the API is useful for automation, bulk imports, and version-controlled tooling.

The base path is /api/v2/datacollectionconf.

Endpoint overview

All paths are relative to the base path. For the request and response bodies, see the OpenAPI definition at /api/v2/openapi.json.

Method Path Description

Upload

POST

/upload

Upload source XML files and datacollection-config.xml. See Upload XML.

Profiles

GET

/profiles

List all profiles.

GET

/profiles/{profileId}

Get one profile.

POST

/profiles

Create a profile.

PUT

/profiles/{profileId}

Update a profile.

DELETE

/profiles

Delete profiles. The request body is a JSON array of profile IDs.

PUT

/profiles/enable?enabled={true|false}

Enable or disable profiles. The request body is a JSON array of profile IDs.

POST

/profiles/{profileId}/sources

Attach a source to a profile. The request body is the source name.

DELETE

/profiles/{profileId}/sources/{sourceName}

Detach a source from a profile.

Sources

GET

/filter/collectsources

List sources, with filter, sort and pagination parameters.

GET

/collectsources/names-and-ids

List the name and ID of all sources.

GET

/collectsources/{collectionSourceId}

Get one source.

POST

/collectsources

Create a source.

DELETE

/collectsources?id={id}

Delete sources. Repeat id for more than one source.

PATCH

/collectsources/status/{enabled}?id={id}

Enable or disable sources.

GET

/collectsources/{collectionSourceId}/download

Download a source as a datacollection-group XML or JSON file.

GET

/config/download

Download the top-level datacollection-config file.

MIB groups, resource types and system definitions

GET

/filter/{collectionSourceId}/{mibgroups|resourcetypes|systemdefs}

List the definitions of a source, with filter, sort and pagination parameters.

POST

/collectsources/{collectionSourceId}/{mibgroups|resourcetypes|systemdefs}

Add a definition to a source.

PUT

/collectsources/{collectionSourceId}/mibgroups/{mibGroupId}

Update a MIB group. Resource types and system definitions use the same pattern.

DELETE

/collectsources/{snmpDataCollectionSourceId}/{mib-groups|resource-types|system-defs}?id={id}

Delete definitions from a source.

PATCH

/collectsources/{snmpDataCollectionSourceId}/{mib-groups|resource-types|system-defs}/status/{enabled}?id={id}

Enable or disable definitions in a source.

Lookup by name

GET

/{mibgroups|resourcetypes|systemdefs}/names

List the names of all definitions of this type. The resource type list also contains the instance values 0 and ifIndex.

GET

/{mibgroups|resourcetypes|systemdefs}/by-name?name={name}

Get every definition with this exact name, with the source that defines it. See Find a definition by name.

Upload XML

Use this endpoint to import legacy datacollection-config.xml and etc/datacollection/*.xml files, or any externally version-controlled SNMP data collection definition.

Each upload part must be an XML file whose root element is either:

  • <datacollection-group> — a source definition (registered as a new source on first upload, updated on subsequent uploads).

  • <datacollection-config> — a profile-driver file with <snmp-collection> entries. At most one is allowed per request; its <include-collection> entries drive how new sources are attached.

How profileNames is applied depends on the batch composition:

Batch composition profileNames requirement

All-new sources

Required. New sources are attached to the named profiles.

All-update sources (every source already exists in the DB)

Optional. If non-empty, applied additively to every source.

Mixed (≥1 new and ≥1 update)

Required for the new sources; ignored for updates. Use /profiles/{profileId}/sources to change existing memberships.

<datacollection-config> present in the batch

Ignored — the config’s <include-collection> entries drive attachment.

An <include-collection> entry attaches a full source, or copies a part of a source:

  • dataCollectionGroup="X" attaches the source X to the profile. Later changes to X apply to the profile.

  • dataCollectionGroup="X" with <exclude-filter> entries, and systemDef="Y", copy the selected system definitions and the MIB groups that they name to the source _inline<profile>. The exclude-filter form also copies the resource types of X. The source X, or the source that contains Y, must be a file in the same request. Thus, include the files that datacollection-config.xml refers to in the same upload.

The copy does not change when you edit X later. You can edit inline_<profile> in the UI like any other source. An upload of datacollection-config.xml replaces the content of inline_<profile>, and your edits to it are lost.

If the request does not contain the source of an exclude-filter entry, the upload attaches the full source X and ignores the filter. If the request does not contain the system definition Y, the upload skips it. In both cases, the upload continues, and the errors array of the response contains a message.

Upload one or more source XML files and attach them to the default profile
curl -u admin:admin \
  -X POST "http://localhost:8980/opennms/api/v2/datacollectionconf/upload" \
  -F "upload=@/opt/opennms/etc_archive/datacollection/cisco.xml;type=application/xml" \
  -F "upload=@/opt/opennms/etc_archive/datacollection/juniper.xml;type=application/xml" \
  -F "profileNames=default"

The response body contains per-file success and errors arrays so partial failures are visible without rolling back the whole batch.

Status Meaning

200 OK

Upload processed. Inspect the response body for per-file success/error details.

400 Bad Request

Invalid XML, missing required profileNames for an all-new source-only upload, or other request error.

Find a definition by name

A MIB group, resource type or system definition name can exist in more than one source. Use these endpoints to find every source that defines a name. The Find by Name tab of the admin page uses the same endpoints.

Find every source that defines the mib2-interfaces MIB group
curl -u admin:admin -G "http://localhost:8980/opennms/api/v2/datacollectionconf/mibgroups/by-name" \
  --data-urlencode "name=mib2-interfaces"

The response is a JSON array with one entry for each source that defines the name. Each entry contains the definition, its enabled flag, collectionSourceId and collectionSourceName. The name is a query parameter, so a name that contains a slash, such as Microsoft Windows NT/2000, also works.

Status Meaning

200 OK

At least one source defines the name.

400 Bad Request

The name query parameter is missing or blank.

404 Not Found

No source defines the name.

500 Internal Server Error

The server cannot read the definitions. The server log contains the cause.