コンテンツにスキップ
Yagra

netbox_site_fields

GET
/api/v1/netbox/servers/{id}/site-fields
curl --request GET \
  --url https://example.com/api/v1/netbox/servers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/site-fields \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

The server id

Responses

Section titled “Responses”

200

Section titled “200”

The site-code sources this NetBox offers. Check custom_fields_readable before reading custom_fields as “there are none” — a token without extras.view_customfield gets false and an empty list

Media typeapplication/json

What an operator may choose as the source of a Site’s code.

🚨 Only the custom fields are listed here, deliberately. The built-in Site fields are a closed set the WebUI already knows, so it can label them in the viewer’s language; returning English labels from the API would put untranslatable words in a Japanese form. The API’s job is the half that is unknowable from the code — what this particular NetBox has been given.

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
{
  "built_ins": [
    "slug"
  ]
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

404

Section titled “404”

No such server

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

502

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Section titled “503”

Inventory storage is unavailable (skeleton mode)

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}