Create tag
POST /v1/tags
Create a new tag, optionally with config overrides.
Token scope required: tags:create
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Name of the new tag. Key must not be longer than 20 characters. Value must not be longer than 50 characters. No whitespace around either allowed.
Optional description
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.
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
Example
tun.mtuThe override’s value. Its type depends on key.
Example
1300If specified, the new tag will be inserted before this tag (i.e. will have a lower priority / precedence than the “before” tag.) Cannot specify this in combination with “after.”
If specified, the new tag will be inserted after this tag (i.e. will have a higher priority / precedence than the “after” tag.) Cannot specify this in combination with “before.”
A list of route IDs to which any hosts with this tag will be subscribed.
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.
object
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.
Role ID to allow with this firewall rule. If not specified, all roles are included.
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
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
object
First port number included in range.
Last port number included in range. Must be greater than from port.
Responses
Section titled “ Responses ”Successful operation
object
object
Key is max 20 characters, value is max 50 characters, no whitespace around either allowed
Example
key:valueList 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.
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
Example
tun.mtuThe override’s value. Its type depends on key.
Example
1300Priority 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.
Count of hosts which have the tag assigned.
Route IDs to which any hosts with this tag will be subscribed.
Example
[ "route-X47KHSCOSQJP5IOKNNKRRGHVAI"]Inbound firewall rules applied to every host that carries this tag, in addition to the rules from the host’s role.
object
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.
Role ID to allow with this firewall rule. If not specified, all roles are included.
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
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
object
First port number included in range.
Last port number included in range. Must be greater than from port.
Examples
{ "data": { "name": "env:prod", "description": "Hosts which have live in or have access to production resources", "configOverrides": [ { "key": "logging.level", "value": "info" } ], "priority": 3, "hostCount": 10, "routeSubscriptions": [], "firewallRules": [ { "protocol": "TCP", "description": "allow SSH access from admins", "allowedRoleID": "role-G3TWUQ4FASQEF44MGMTSRBTYKM", "allowedTags": [ "user-type:admin" ], "portRange": { "from": 22, "to": 22 } } ] }}Validation error
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Examples
A tag already exists with the name.
{ "errors": [ { "code": "ERR_DUPLICATE_VALUE", "message": "value already exists", "path": "name" } ]}Cannot find the supplied "before" or "after" tag.
{ "errors": [ { "code": "ERR_INVALID_REFERENCE", "message": "invalid tag location", "path": "before" } ]}Only one of "before" or "after" may be specified.
{ "errors": [ { "code": "ERR_INVALID_VALUE", "message": "may only set before or after, not both", "path": "before" }, { "code": "ERR_INVALID_VALUE", "message": "may only set before or after, not both", "path": "after" } ]}The API key is missing, invalid or expired.
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Example
{ "errors": [ { "code": "ERR_UNAUTHORIZED", "message": "unauthorized" } ]}The API key lacks a required scope.
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Examples
The API key lacks a required scope.
{ "errors": [ { "code": "ERR_FORBIDDEN", "message": "api key must support the following scopes: hosts:read" } ]}The organization has exceeded its API request rate limit. Retry the request after a short delay.
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Example
{ "errors": [ { "code": "ERR_TOO_MANY_REQUESTS", "message": "too many requests" } ]}