start_discovery_scan

POST

/api/v1/discovery/scan

curl --request POST \
  --url https://example.com/api/v1/discovery/scan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "communities": [ "example" ], "credential_ids": [ "example" ], "pool": "example", "snmp_when_unreachable": true, "targets": [ "example" ] }'

Authorizations

• bearer

Request Body^required

Media typeapplication/json

Start-scan body: explicit target IPs (the WebUI expands a CIDR), candidate stored credentials by id, and ad-hoc communities.

object

communities

Array<string>

credential_ids

Array<string>

pool

Poll-pool to run the sweep in (ADR-009/020). Absent/empty = legacy global discovery.

string | null

snmp_when_unreachable

Try SNMP on addresses that do not answer ICMP.

Absent means no. Earlier releases had no such option and tried every address in the range with every candidate credential, which is why sweeping a /24 took minutes; set this to get that behaviour back, and with it a device that filters ICMP but answers SNMP.

boolean

targets

required

Array<string>

Example^generated

{
  "communities": [
    "example"
  ],
  "credential_ids": [
    "example"
  ],
  "pool": "example",
  "snmp_when_unreachable": true,
  "targets": [
    "example"
  ]
}

Responses

202

Sweep accepted; poll its status by id

Media typeapplication/json

The accepted scan’s id, for polling its status.

object

scan_id

required

string format: uuid

Example^generated

{
  "scan_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

400

No targets or more than the cap, an unparseable address, or a named credential that is missing or unusable

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks ManageConfig

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Skeleton mode has no write side, or this core is not the HA leader

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}