Edit route

PUT

/v1/routes/{routeID}

• Default server

Token scope required: routes:update

Caution: Any properties not provided in the request will be reset to their default values. If only changing one firewall rule, be sure to include the others as well, otherwise they will be removed.

Authorizations

• ApiToken
  routes:update

Parameters

Path Parameters

routeID

required

string

Example

route-X47KHSCOSQJP5IOKNNKRRGHVAI

Request Body ^required

object

name

required

string

>= 1 characters <= 50 characters

description

string

<= 255 characters

routerHostID

string

routableCIDRs

Keys of object should be IPv4 CIDR ranges, values are an object with an ‘install’ boolean.

object

<= 20 properties

key

additional properties

object

install

boolean

firewallRules

Incoming firewall rules. Will replace existing list of rules.

Array<object>

<= 50 items

object

localCIDR

CIDR range within the routableCIDRs this rule will apply to. Use “0.0.0.0/0” for all IP addresses.

string format: ipv4/cidr

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

Responses

200

Successful operation

object

data

required

object

id

required

string

name

required

string

description

required

string

createdAt

required

string format: date-time

modifiedAt

required

string format: date-time

routerHostID

required

string | null

routableCIDRs

required

Keys of object should be IPv4 CIDR ranges, values are an object with an ‘install’ boolean.

object

key

additional properties

object

install

required

boolean

firewallRules

required

Array

object

localCIDR

CIDR range within the routableCIDRs this rule will apply to. Use “0.0.0.0/0” for all IP addresses.

string format: ipv4/cidr

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

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

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

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

routerHostID does not exist.

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

The router host has no IPv4 address but routableCIDRs includes an IPv4 CIDR.

{
  "errors": [
    {
      "code": "ERR_INVALID_REFERENCE",
      "message": "router host must have an IPv4 address to route IPv4 CIDRs",
      "path": "routerHostID"
    }
  ]
}

allowedRoleID does not exist.

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

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

404

Route 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

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