test_netbox_connection

POST

/api/v1/netbox/test

curl --request POST \
  --url https://example.com/api/v1/netbox/test \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "base_url": "example", "ca_cert_pem": "example", "token": "example" }'

Authorizations

• bearer

Request Body^required

Media typeapplication/json

object

base_url

required

string

ca_cert_pem

string | null

token

required

string

Example^generated

{
  "base_url": "example",
  "ca_cert_pem": "example",
  "token": "example"
}

Responses

200

The probe ran. Check reachable and authenticated — a refused token is a 200 here, not an error, because the operator needs to see which of the two fields is wrong

Media typeapplication/json

What a connection test found.

🚨 The two booleans are separate because a single 403 cannot tell them apart, and that is the whole value of this endpoint. NetBox requires authentication on /api/status/, but it sends its API-Version header on every response including the unauthenticated refusal — so reachable && !authenticated means “right address, wrong token”, while !reachable means “not a NetBox, or not that address”. Collapsing them sends the operator to check the wrong field.

object

api_version

The API-Version header (e.g. 4.6), present even when the token was refused.

string | null

authenticated

required

…and it accepted the token.

boolean

netbox_version

The full netbox-version (e.g. 4.6.9), available only once authenticated.

string | null

reachable

required

Something at that URL answered as a NetBox API.

boolean

site_id_fields

One of:

null

null

object

The site-code sources this NetBox offers, or null when the token was refused — there is nothing to list if we never got in. This rides along with the probe because pressing “test connection” is the only moment an unsaved server’s token exists on the server side.

object

built_ins

required

The built-in Site fields, so the set has exactly one author. The WebUI labels these itself (they are a closed set, so the labels are translatable) and renders them without waiting for this call; what it takes from here is the guarantee that its list is the whole list.

Array<string>

Allowed values: slug facility description

custom_fields

required

Array<object>

One NetBox custom field that could supply a site code.

object

label

required

NetBox’s own label for the field, or its key when NetBox has no label. Not translatable — it is this deployment’s own wording.

string

value

required

Store this verbatim in site_id_field.

string

custom_fields_readable

required

🚨 false means the token may not read /api/extras/custom-fields/ — not that this NetBox has none. The form offers a type-it-in box in that case, and collapsing the two would leave the operator reading “there are no custom fields here” and never finding it. This is the same distinction, for the same reason, that [TestNetboxResult] draws between reachable and authenticated.

boolean

Example

{
  "site_id_fields": {
    "built_ins": [
      "slug"
    ]
  }
}

400

Base_url is malformed or refused by the SSRF policy, or the CA certificate is invalid

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

502

The NetBox call failed; the detail is logged, never returned

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