Skip to content

Add IPv4 address to host

POST
/v2/hosts/{hostID}/ip-addresses

Assign an IPv4 address to a host that does not have one, such as a host created before its network gained an IPv4 CIDR. A host may have at most one IPv4 address.

Token scope required: hosts:update

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
hostID
required
string
Example
host-24NVITKMNU3CYCEDNFWKAOBX7I

Request Body required

Section titled “Request Body required ”
object
ipAddress
required

An IPv4 address to assign, or the network’s IPv4 CIDR to auto-assign the next available address within it.

string
Example
100.100.0.29

Responses

Section titled “ Responses ”

200

Section titled “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
ipAddresses
required

List of IP addresses assigned to this host within the overlay network. On dual-stack networks this includes both an IPv4 and IPv6 address. On IPv6-only networks this contains only an IPv6 address.

Array<string>
staticAddresses
required
Array<string>
listenPort
required

Will be zero if a regular host

integer format: int32
<= 65535
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
1300
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",
    "ipAddresses": [
      "100.100.0.29",
      "fdef:c0:c0:1::1d"
    ],
    "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

Section titled “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

`ipAddress` is not an IPv4 address or IPv4 CIDR.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must be a valid IPv4 address or IPv4 CIDR",
      "path": "ipAddress"
    }
  ]
}

401

Section titled “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

Section titled “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

Section titled “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

Section titled “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"
    }
  ]
}