Edit host (legacy)

Authorizations

ApiToken
hosts:update

Path Parameters

hostID

required

string

Example

host-24NVITKMNU3CYCEDNFWKAOBX7I

Request Body^required

object

name

required

Name of the host

string

>= 1 characters <= 255 characters

Example

My updated host

roleID

ID of the role you want to assign

string | null

Example

role-PZEDBXHQEXKACJPZ6XOQTIAJA4

staticAddresses

List of static IPv4:port/hostname:port addresses. At least one is required if isLighthouse is true.

Array<string>

<= 100 items

Example

[
  "84.123.10.1:4242"
]

listenPort

The UDP port nebula should use on the host. An available port will be automatically selected if 0 is specified. A non-zero port number is required for lighthouses and relays.

integer

0 <= 65535

tags

Array<string>

configOverrides

List of config overrides for the nebula config. Omitting this field clears it; include the host’s current value to keep it unchanged.

Array<object>

ConfigOverride

A single Nebula config override. key names the Nebula config option and determines the type of value; see Config override keys for the documented keys and their value types, and the Nebula config reference for what each option does.

object

key

required

string

Example

tun.mtu

value

required

The override’s value. Its type depends on key.

Example

200

Successful operation

object

data

required

object

id

required

string

organizationID

required

string

networkID

required

string

roleID

required

string | null

endpointOIDCUserID

required

string | null

name

required

string

ipAddress

required

string format: ipv4

staticAddresses

required

Array<string>

listenPort

required

Will be zero if a regular host

integer format: int64

isLighthouse

required

boolean

isRelay

required

boolean

isBlocked

required

boolean

createdAt

required

string format: date-time

modifiedAt

required

string format: date-time

tags

required

Array<string>

configOverrides

required

List of config overrides for the nebula config. Each key may appear at most once. Responses may include keys that aren’t documented; since setting overrides replaces the whole list, keep entries you don’t recognize when writing a list back.

Array<object>

ConfigOverride

A single Nebula config override. key names the Nebula config option and determines the type of value; see Config override keys for the documented keys and their value types, and the Nebula config reference for what each option does.

object

key

required

string

Example

tun.mtu

value

required

The override’s value. Its type depends on key.

Example

metadata

required

Information reported by the host when it last checked in. Fields are null until the host has checked in.

object

lastSeenAt

required

string | null format: date-time

version

required

string | null

platform

required

Client platform reported by the host, or null if unknown. Known values are dnclient, dnclient-desktop and mobile. New values may be added, so clients should accept values not listed here.

string | null

os

required

Operating system reported by the client, or null if unknown. Known values are aix, android, dragonfly, freebsd, hurd, illumos, ios, linux, macos, nacl, netbsd, openbsd, plan9, solaris, wasm, windows and zos. New values may be added, so clients should accept values not listed here.

string | null

updateAvailable

required

boolean

Example

{
  "data": {
    "id": "host-24NVITKMNU3CYCEDNFWKAOBX7I",
    "organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA",
    "networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
    "roleID": "role-PZEDBXHCEXKAKJPZ6XOQTIAJA4",
    "endpointOIDCUserID": null,
    "name": "Host 1",
    "ipAddress": "100.100.0.29",
    "staticAddresses": [],
    "listenPort": 0,
    "isLighthouse": false,
    "isRelay": false,
    "isBlocked": false,
    "createdAt": "2025-01-25T18:15:27Z",
    "modifiedAt": "2025-01-25T18:15:27Z",
    "tags": [
      "env:prod"
    ],
    "configOverrides": [],
    "metadata": {
      "lastSeenAt": "2025-01-25T18:15:27Z",
      "os": "linux",
      "platform": "dnclient",
      "updateAvailable": false,
      "version": "0.9.3"
    }
  }
}

400

Validation error

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Examples

The host is not on an IPv4-only network. Use PUT /v3/hosts/{hostID} instead.

{
  "errors": [
    {
      "code": "ERR_CERT_VERSION_2_INCOMPATIBLE",
      "message": "hosts on v2 networks must be managed via POST/GET /v2/hosts and PUT /v3/hosts endpoints"
    }
  ]
}

A host already exists with the name.

{
  "errors": [
    {
      "code": "ERR_DUPLICATE_VALUE",
      "message": "value already exists",
      "path": "name"
    }
  ]
}

Cannot find the supplied roleID.

{
  "errors": [
    {
      "code": "ERR_INVALID_REFERENCE",
      "message": "referenced value is invalid (perhaps it does not exist?)",
      "path": "roleID"
    }
  ]
}

A tag is not in `key:value` format.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must have 1 and only 1 colon separator",
      "path": "tags[0]"
    }
  ]
}

A lighthouse requires at least one static IP address.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "lighthouse hosts must have at least one static ip address",
      "path": "staticAddresses"
    }
  ]
}

A lighthouse requires a static listen port, like `4242`.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "lighthouse hosts must specify a static (non-zero) listen port",
      "path": "listenPort"
    }
  ]
}

A relay requires a static listen port, like `4242`.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "relay hosts must specify a static (non-zero) listen port",
      "path": "listenPort"
    }
  ]
}

401

The API key is missing, invalid or expired.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_UNAUTHORIZED",
      "message": "unauthorized"
    }
  ]
}

403

The API key lacks a required scope.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Examples

The API key lacks a required scope.

{
  "errors": [
    {
      "code": "ERR_FORBIDDEN",
      "message": "api key must support the following scopes: hosts:read"
    }
  ]
}

404

Host not found

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_NOT_FOUND",
      "message": "resource not found"
    }
  ]
}

429

The organization has exceeded its API request rate limit. Retry the request after a short delay.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_TOO_MANY_REQUESTS",
      "message": "too many requests"
    }
  ]
}

Edit host (legacy)

Authorizations

Parameters

Path Parameters

Example

Request Body required

Example

Example

Example

Example

Example

Responses

200

Example

Example

Example

400

Examples

401

Example

403

Examples

404

Example

429

Example

Request Body^required