Create host (legacy)

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

ipAddress

Assign an IP address to be used within the Managed Nebula network. Must be within the network’s CIDR range. Will be chosen automatically if not provided.

string format: ipv4

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

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": "My new host",
    "ipAddress": "100.100.0.29",
    "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": "2025-01-25T18:15:27Z",
      "os": "linux",
      "platform": "dnclient",
      "updateAvailable": false,
      "version": "0.8.4"
    }
  }
}

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

A host with the ipAddress supplied already exists.

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

Cannot find the supplied roleID.

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

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

A host cannot be created because the network has no addresses left to assign.

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

The network is not IPv4-only. Use POST /v2/hosts 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"
    }
  ]
}

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 (legacy)

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