Skip to content

Update tag

PATCH
/v1/tags/{tag}

Update some of a tag’s fields, leaving the rest unchanged.

Token scope required: tags:update

An omitted field keeps its current value. A provided field replaces the current value wholesale, and an explicit null clears it, the same as an empty list or string. before and after move the tag; omit both to keep its priority.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
tag
required
string
Example
env:prod

Request Body required

Section titled “Request Body required ”
object
description
string | null
<= 255 characters
configOverrides
One of:

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
before

If specified, the tag will be moved before this tag (i.e. will have a lower priority / precedence than the “before” tag.) Cannot be specified in combination with “after.”

string format: key:value
after

If specified, the tag will be moved after this tag (i.e. will have a higher priority / precedence than the “after” tag.) Cannot be specified in combination with “before.”

string format: key:value
routeSubscriptions

A list of route IDs to which any hosts with this tag will be subscribed.

array | null
<= 100 items
firewallRules

A list of inbound firewall rules to apply to every host that carries this tag, in addition to the rules from the host’s role.

array | null
<= 50 items
object
protocol
required

One of ANY, TCP, UDP or ICMP when creating or updating a rule. Responses may include protocols added later, so clients should accept values not listed here.

string
description
string
<= 255 characters
allowedRoleID

Role ID to allow with this firewall rule. If not specified, all roles are included.

string | null
allowedTags

Tags to allow with this firewall rule. An empty list allows all tags; responses return null instead of an empty list. key is max 20 characters, value is max 50 characters, no whitespace around either allowed

array | null
portRange

Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.

object
from
required

First port number included in range.

integer
>= 1 <= 65535
to
required

Last port number included in range. Must be greater than from port.

integer
>= 1 <= 65535
Example
{
  "description": "Hosts which live in or have access to production resources",
  "after": "env:staging"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful operation

object
data
required
object
name
required

Key is max 20 characters, value is max 50 characters, no whitespace around either allowed

string format: key:value
Example
key:value
description
required
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
priority
required

Priority is managed by the API. Use “before” and “after” inputs to order tags. Config overrides associated with tags of a higher (greater) priority take precedence over lower priorities.

integer
hostCount
required

Count of hosts which have the tag assigned.

integer format: int64
routeSubscriptions
required

Route IDs to which any hosts with this tag will be subscribed.

Array<string>
Example
[
  "route-X47KHSCOSQJP5IOKNNKRRGHVAI"
]
firewallRules
required

Inbound firewall rules applied to every host that carries this tag, in addition to the rules from the host’s role.

Array
object
protocol
required

One of ANY, TCP, UDP or ICMP when creating or updating a rule. Responses may include protocols added later, so clients should accept values not listed here.

string
description
string
<= 255 characters
allowedRoleID

Role ID to allow with this firewall rule. If not specified, all roles are included.

string | null
allowedTags

Tags to allow with this firewall rule. An empty list allows all tags; responses return null instead of an empty list. key is max 20 characters, value is max 50 characters, no whitespace around either allowed

array | null
portRange

Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.

object
from
required

First port number included in range.

integer
>= 1 <= 65535
to
required

Last port number included in range. Must be greater than from port.

integer
>= 1 <= 65535

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

Cannot find the supplied "before" or "after" tag.

{
  "errors": [
    {
      "code": "ERR_INVALID_REFERENCE",
      "message": "invalid tag location",
      "path": "before"
    }
  ]
}

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 ”

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