Create route

POST /v1/routes

Create a new route.

Token scope required: routes:create

Request

application/json

Request Body required

name string required
Possible values: non-empty and <= 50 characters
Name of the new route
description string
Possible values: <= 255 characters
Optional description
routerHostID string
routableCIDRs object
Keys of object should be IPv4 CIDR ranges, values are an object with an 'install' boolean.
property name* object
install boolean
firewallRules object[]
Route firewall rules
Array [
localCIDR ipv4/cidr
CIDR range within the routableCIDRs this rule will apply to. Use "0.0.0.0/0" for all IP addresses.
protocol string required
Possible values: [ANY, TCP, UDP, ICMP]
description string
Possible values: <= 255 characters
allowedRoleID string nullable
Role ID to allow with this firewall rule. If not specified, all roles are included.
allowedTags key:value[]
Tags to allow with this firewall rule. An empty list allows all tags. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
portRange object nullable
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
from integer required
Possible values: >= 1 and <= 65535
First port number included in range.
to integer required
Possible values: >= 1 and <= 65535
Last port number included in range. Must be greater than from port.
]

Responses

Successful operation

application/json

Schema
Example (from schema)

Schema

data object
id string
name string
description string
createdAt date-time
modifiedAt date-time
routerHostID string
routableCIDRs object
Keys of object should be IPv4 CIDR ranges, values are an object with an 'install' boolean.
property name* object
install boolean
firewallRules object[]
Array [
localCIDR ipv4/cidr
CIDR range within the routableCIDRs this rule will apply to. Use "0.0.0.0/0" for all IP addresses.
protocol string required
Possible values: [ANY, TCP, UDP, ICMP]
description string
Possible values: <= 255 characters
allowedRoleID string nullable
Role ID to allow with this firewall rule. If not specified, all roles are included.
allowedTags key:value[]
Tags to allow with this firewall rule. An empty list allows all tags. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
portRange object nullable
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
from integer required
Possible values: >= 1 and <= 65535
First port number included in range.
to integer required
Possible values: >= 1 and <= 65535
Last port number included in range. Must be greater than from port.
]
metadata object

{
  "data": {
    "id": "route-X47KHSCOSQJP5IOKNNKRRGHVAI",
    "name": "My new route",
    "description": "",
    "routerHostID": "host-24NVITKMNU3CYCEDNFWKAOBX7I",
    "routableCIDRs": {
      "192.168.14.0/26": {
        "install": true
      }
    },
    "createdAt": "2024-03-15T13:59:09Z",
    "modifiedAt": "2024-03-15T13:59:09Z",
    "firewallRules": [
      {
        "protocol": "TCP",
        "localCIDR": "192.168.14.56/32",
        "description": "allow SSH access",
        "allowedRoleID": "role-G3TWUQ4FASQEF44MGMTSRBTYKM",
        "portRange": {
          "from": 22,
          "to": 22
        }
      }
    ]
  },
  "metadata": {}
}

Validation error

application/json

Schema

errors object[] required
Array [
code string required
A static name for the error type
message string required
A short human readable description of the error
path string nullable
Describes the variable missing or malformed
]

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "path": "string"
    }
  ]
}

name not specified.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE_LENGTH",
      "message": "must have a length between 1 and 50",
      "path": "name"
    }
  ]
}

A route with the name already exists.

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

Invalid protocol value.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must be a valid protocol: ANY, TCP, UDP, ICMP",
      "path": "firewallRules[0].protocol"
    }
  ]
}

Invalid/missing from and to values.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must be between 1 and 65535",
      "path": "firewallRules[0].portRange.from"
    },
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must be between 1 and 65535",
      "path": "firewallRules[0].portRange.to"
    }
  ]
}

From cannot be greater than to

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "from must be less than or equal to to",
      "path": "firewallRules[0].portRange"
    }
  ]
}

Create route

Request​

Request