
= Discovery

Use this endpoint to trigger a one-time discovery scan.

== POST (submitting one-time scan configuration)

[caption=]
.Discovery POST function
[options="autowidth"]
|===
| Resource  | Description

| /opennms/api/v2/discovery
| Submits a one-time scan configuration.
|===

The following XML structure is used to define a scan job.

.Sample configuration file `discovery.xml`
[source,XML]
----
<discoveryConfiguration>
  <specifics>
    <specific>
      <location>Default</location>
      <retries>3</retries>
      <timeout>2000</timeout>
      <foreignSource>My-ForeignSource</foreignSource>
      <content>192.0.2.1</content>
    </specific>
  </specifics>
  <includeRanges>
    <includeRange>
      <location>Default</location>
      <retries>3</retries>
      <timeout>2000</timeout>
      <foreignSource>My-ForeignSource</foreignSource>
      <begin>192.0.2.10</begin>
      <end>192.0.2.254</end>
    </includeRange>
  </includeRanges>
  <excludeRanges>
    <excludeRange>
      <begin>192.0.2.60</begin>
      <end>192.0.2.65</end>
    </excludeRange>
  </excludeRanges>
  <includeUrls>
    <includeUrl>
      <location>Default</location>
      <retries>3</retries>
      <timeout>2000</timeout>
      <foreignSource>My-ForeignSource</foreignSource>
      <content>http://192.0.2.254/addresses.txt</content>
    </includeUrl>
  </includeUrls>
</discoveryConfiguration>
----

Trigger the scan itself by posting the configuration to the REST endpoint as follows:

.Trigger one-time scan
[source, bash]
----
curl -H "Content-Type: application/xml" -u admin:admin -X POST -d @discovery.xml http://localhost:8980/opennms/api/v2/discovery
----
