Promote a discovered endpoint to a monitored node.

POST

/api/v1/discovered-endpoints/{id}/import

curl --request POST \
  --url https://example.com/api/v1/discovered-endpoints/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "credential_id": "example", "file_by_prefix": true, "group_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "model": "example", "name": "example", "profile_id": "example", "vendor": "example" }'

Builds the same NewNode a scan import does and goes through the same writer, so classification (sysDescr → maker/model) happens on the node’s first identity probe exactly as it does for any other node — there is no second creation path to keep in step.

409 means the address is already an inventory node. That is not a failure of the import so much as an answer: the endpoint stopped being unmonitored between the list being read and the button being pressed, and the row is reconciled on the way out so the list stops showing it.

Authorizations

• bearer

Parameters

Path Parameters

id

required

string format: uuid

Discovered-endpoint id

Request Body^required

Media typeapplication/json

What to call the endpoint, and what to bind it to, when promoting it to a node.

object

credential_id

string | null

file_by_prefix

File the node into the folder whose IP range holds its address, as the range-scan import does (ADR-131). Omitted: false, as before.

boolean

group_id

The folder the node goes into — or, with file_by_prefix, where it goes when no folder’s IP range claims its address (ADR-179 Inc.8). Omitted: the tree root, as before.

string | null format: uuid

model

Model, from the same probe as vendor.

string | null

name

Node name. Defaults to the address when omitted or blank.

string | null

profile_id

string | null

vendor

Maker, as a probe of this endpoint classified it from sysDescr (ADR-179 Inc.2). Omitted when nothing was probed; the node’s first identity read fills it then, as before.

string | null

Example^generated

{
  "credential_id": "example",
  "file_by_prefix": true,
  "group_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "model": "example",
  "name": "example",
  "profile_id": "example",
  "vendor": "example"
}

Responses

201

The endpoint is now a monitored node

Media typeapplication/json

How many nodes an import created, and — when filing by IP range was asked for — how.

object

created

required

integer format: int32

filed

One of:

null

null

object

Present when the request set file_by_prefix, or — on a scan import — named a folder for any row itself. Absent otherwise: an endpoint promotion without file_by_prefix (a group_id alone does not bring it), and every scan import that decided nothing per row.

⚠️ skip_serializing_if rather than a zero-filled struct: an import that filed nothing by range would read as one that filed zero rows, and with the field absent the wire shape is what every existing client already parses. The endpoint import (ADR-179 Inc.8) fills it only when it was asked to file by range, and never counts chosen. It counts the rows that were created — a skipped row was filed nowhere. With file_by_prefix set, created == matched + ambiguous + unmatched + chosen; with it off, only chosen is counted and the rest went to group_id.

object

ambiguous

required

Two or more folders claimed it at the same prefix length; filed into the fallback.

integer format: int32

chosen

required

The operator named this row’s folder themselves, so no rule was applied to it (ADR-131 decision 11). Counted apart from the three above because it is not an outcome of the match — reporting it as matched would credit the rule with a choice a person made.

integer format: int32

matched

required

Filed into the one folder whose range contains the address.

integer format: int32

unmatched

required

No folder’s range contained it; filed into the fallback.

integer format: int32

skipped_existing

required

Rows not created because a device node already stands at that address — or because an earlier row of the same request has just put one there. created + skipped_existing is the number of rows the request carried. 0 when nothing was skipped.

A URL or DNS monitor at the same address does not count: those store a resolved address, and the device itself is still importable.

integer format: int32

Example^generated

{
  "created": 1,
  "filed": {
    "ambiguous": 1,
    "chosen": 1,
    "matched": 1,
    "unmatched": 1
  },
  "skipped_existing": 1
}

400

A binding id that is not a UUID, or a group_id no folder has

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, or (out_of_scope) a folder-scoped caller’s node would land in the tree root, which it cannot see — name a folder, or one whose IP range holds the address; nothing is written

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

404

No such discovered endpoint, or not one the caller can see, or (group_not_found) a group_id outside the caller’s folders

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

409

That address is already a monitored node, or (sender_only) only a syslog or trap sender vouches for it — a sender’s address can be forged, so it is never imported

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

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