Create host

Authorizations

ApiToken
hosts:create

Request Body^required

object

name

required

Name of the new host

string

>= 1 characters <= 255 characters

Example

My new host

networkID

required

ID of your network

string

Example

network-KAOWMXZHZWCVMGGFKM22XEGYLE

roleID

ID of the role you want to assign

string | null

Example

role-PZEDBXHQEXKACJPZ6XOQTIAJA4

ipAddresses

List of IP addresses to assign, and/or IPv4/IPv6 CIDR prefixes to auto-assign within. A host may have at most one IPv4 address and one IPv6 address.

On IPv6-capable networks, an IPv6 address is always auto-assigned unless one is specified. On IPv4-only networks, an IPv4 address is always auto-assigned unless one is specified. On dual-stack networks, an IPv4 address is assigned only if you specify an IPv4 address or an IPv4 CIDR prefix to auto-assign within.

Array<string>

<= 2 items

Example

[
  "100.100.0.29"
]

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

isLighthouse

Set to true to create a new lighthouse. A lighthouse cannot also be a relay.

boolean

isRelay

Set to true to create a new relay. A relay cannot also be a lighthouse.

boolean

tags

Array<string>

configOverrides

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

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

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": "My new host",
    "ipAddresses": [
      "100.100.0.29",
      "fdef:c0:c0:1::1d"
    ],
    "staticAddresses": [
      "84.123.10.1:4242"
    ],
    "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": null,
      "os": null,
      "platform": null,
      "updateAvailable": false,
      "version": null
    }
  }
}

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

A host already exists with the name.

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

Cannot find the supplied networkID.

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

Cannot find the supplied roleID.

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

The requested IP address is outside the network's CIDR.

{
  "errors": [
    {
      "code": "ERR_OUT_OF_RANGE",
      "message": "value falls outside of the allowed range",
      "path": "ipAddresses[0]"
    }
  ]
}

The requested IP address is already assigned to another host.

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

The network has no IP addresses left to assign.

{
  "errors": [
    {
      "code": "ERR_NETWORK_FULLY_ALLOCATED",
      "message": "there are no IP addresses available for assignment in the network"
    }
  ]
}

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 host may be a lighthouse OR a relay, but not both.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "lighthouse hosts must not also be relay hosts"
    }
  ]
}

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

The organization has reached its host limit.

{
  "errors": [
    {
      "code": "ERR_LIMIT_EXCEEDED",
      "message": "no more than 100 hosts are allowed",
      "extra": {
        "limit": 100,
        "limitName": "hosts"
      }
    }
  ]
}

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

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

Create host

Authorizations

Request Body required

Example

Example

Example

Example

Example

Example

Example

Responses

200

Example

Example

Example

400

Examples

401

Example

403

Examples

429

Example

Request Body^required