Magic Transit
ModelsExpand Collapse
HealthCheck { enabled, rate, target, type }
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
Magic TransitApps
List Apps
Create a new App
Update an App
Update an App
Delete Account App
ModelsExpand Collapse
AppListResponse = { account_app_id, hostnames, ip_subnets, 3 more } or { managed_app_id, hostnames, ip_subnets, 3 more } Collection of Hostnames and/or IP Subnets to associate with traffic decisions.
Collection of Hostnames and/or IP Subnets to associate with traffic decisions.
MagicAccountApp { account_app_id, hostnames, ip_subnets, 3 more } Custom app defined for an account.
Custom app defined for an account.
MagicManagedApp { managed_app_id, hostnames, ip_subnets, 3 more } Managed app defined by Cloudflare.
Managed app defined by Cloudflare.
AppCreateResponse { account_app_id, hostnames, ip_subnets, 3 more } Custom app defined for an account.
Custom app defined for an account.
AppUpdateResponse { account_app_id, hostnames, ip_subnets, 3 more } Custom app defined for an account.
Custom app defined for an account.
AppEditResponse { account_app_id, hostnames, ip_subnets, 3 more } Custom app defined for an account.
Custom app defined for an account.
AppDeleteResponse { account_app_id, hostnames, ip_subnets, 3 more } Custom app defined for an account.
Custom app defined for an account.
Magic TransitCf Interconnects
List interconnects
List interconnect Details
Update interconnect
Update multiple interconnects
ModelsExpand Collapse
CfInterconnectListResponse { interconnects }
interconnects: optional array of { id, automatic_return_routing, colo_name, 10 more }
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
The name of the interconnect. The name cannot share a name with other tunnels.
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
CfInterconnectGetResponse { interconnect }
interconnect: optional { id, automatic_return_routing, colo_name, 10 more }
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
The name of the interconnect. The name cannot share a name with other tunnels.
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
CfInterconnectUpdateResponse { modified, modified_interconnect }
modified_interconnect: optional { id, automatic_return_routing, colo_name, 10 more }
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
The name of the interconnect. The name cannot share a name with other tunnels.
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
CfInterconnectBulkUpdateResponse { modified, modified_interconnects }
modified_interconnects: optional array of { id, automatic_return_routing, colo_name, 10 more }
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
The name of the interconnect. The name cannot share a name with other tunnels.
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
Magic TransitGRE Tunnels
List GRE tunnels
List GRE Tunnel Details
Create a GRE tunnel
Update GRE Tunnel
Delete GRE Tunnel
Update multiple GRE tunnels
ModelsExpand Collapse
GRETunnelListResponse { gre_tunnels }
gre_tunnels: optional array of { id, cloudflare_gre_endpoint, customer_gre_endpoint, 12 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
The name of the tunnel. The name cannot contain spaces or special characters, must be 15 characters or less, and cannot share a name with another GRE tunnel.
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
GRETunnelGetResponse { gre_tunnel }
gre_tunnel: optional { id, cloudflare_gre_endpoint, customer_gre_endpoint, 12 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
The name of the tunnel. The name cannot contain spaces or special characters, must be 15 characters or less, and cannot share a name with another GRE tunnel.
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
GRETunnelCreateResponse { id, cloudflare_gre_endpoint, customer_gre_endpoint, 12 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
The name of the tunnel. The name cannot contain spaces or special characters, must be 15 characters or less, and cannot share a name with another GRE tunnel.
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
GRETunnelUpdateResponse { modified, modified_gre_tunnel }
modified_gre_tunnel: optional { id, cloudflare_gre_endpoint, customer_gre_endpoint, 12 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
The name of the tunnel. The name cannot contain spaces or special characters, must be 15 characters or less, and cannot share a name with another GRE tunnel.
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
GRETunnelDeleteResponse { deleted, deleted_gre_tunnel }
deleted_gre_tunnel: optional { id, cloudflare_gre_endpoint, customer_gre_endpoint, 12 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
The name of the tunnel. The name cannot contain spaces or special characters, must be 15 characters or less, and cannot share a name with another GRE tunnel.
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
GRETunnelBulkUpdateResponse { modified, modified_gre_tunnels }
modified_gre_tunnels: optional array of { id, cloudflare_gre_endpoint, customer_gre_endpoint, 12 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
The name of the tunnel. The name cannot contain spaces or special characters, must be 15 characters or less, and cannot share a name with another GRE tunnel.
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
Magic TransitIPSEC Tunnels
List IPsec tunnels
List IPsec tunnel details
Create an IPsec tunnel
Update IPsec Tunnel
Delete IPsec Tunnel
Update multiple IPsec tunnels
Generate Pre Shared Key (PSK) for IPsec tunnels
ModelsExpand Collapse
IPSECTunnelListResponse { ipsec_tunnels }
ipsec_tunnels: optional array of { id, cloudflare_endpoint, interface_address, 14 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
When true, the tunnel can use a null-cipher (ENCR_NULL) in the ESP tunnel (Phase 2).
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
custom_remote_identities: optional { fqdn_id }
A custom IKE ID of type FQDN that may be used to identity the IPsec tunnel. The generated IKE IDs can still be used even if this custom value is specified.
Must be of the form <custom label>.<account ID>.custom.ipsec.cloudflare.com.
This custom ID does not need to be unique. Two IPsec tunnels may have the same custom fqdn_id. However, if another IPsec tunnel has the same value then the two tunnels cannot have the same cloudflare_endpoint.
The IP address assigned to the customer side of the IPsec tunnel. Not required, but must be set for proactive traceroutes to work.
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
IPSECTunnelGetResponse { ipsec_tunnel }
ipsec_tunnel: optional { id, cloudflare_endpoint, interface_address, 14 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
When true, the tunnel can use a null-cipher (ENCR_NULL) in the ESP tunnel (Phase 2).
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
custom_remote_identities: optional { fqdn_id }
A custom IKE ID of type FQDN that may be used to identity the IPsec tunnel. The generated IKE IDs can still be used even if this custom value is specified.
Must be of the form <custom label>.<account ID>.custom.ipsec.cloudflare.com.
This custom ID does not need to be unique. Two IPsec tunnels may have the same custom fqdn_id. However, if another IPsec tunnel has the same value then the two tunnels cannot have the same cloudflare_endpoint.
The IP address assigned to the customer side of the IPsec tunnel. Not required, but must be set for proactive traceroutes to work.
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
IPSECTunnelCreateResponse { id, cloudflare_endpoint, interface_address, 14 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
When true, the tunnel can use a null-cipher (ENCR_NULL) in the ESP tunnel (Phase 2).
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
custom_remote_identities: optional { fqdn_id }
A custom IKE ID of type FQDN that may be used to identity the IPsec tunnel. The generated IKE IDs can still be used even if this custom value is specified.
Must be of the form <custom label>.<account ID>.custom.ipsec.cloudflare.com.
This custom ID does not need to be unique. Two IPsec tunnels may have the same custom fqdn_id. However, if another IPsec tunnel has the same value then the two tunnels cannot have the same cloudflare_endpoint.
The IP address assigned to the customer side of the IPsec tunnel. Not required, but must be set for proactive traceroutes to work.
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
IPSECTunnelUpdateResponse { modified, modified_ipsec_tunnel }
modified_ipsec_tunnel: optional { id, cloudflare_endpoint, interface_address, 14 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
When true, the tunnel can use a null-cipher (ENCR_NULL) in the ESP tunnel (Phase 2).
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
custom_remote_identities: optional { fqdn_id }
A custom IKE ID of type FQDN that may be used to identity the IPsec tunnel. The generated IKE IDs can still be used even if this custom value is specified.
Must be of the form <custom label>.<account ID>.custom.ipsec.cloudflare.com.
This custom ID does not need to be unique. Two IPsec tunnels may have the same custom fqdn_id. However, if another IPsec tunnel has the same value then the two tunnels cannot have the same cloudflare_endpoint.
The IP address assigned to the customer side of the IPsec tunnel. Not required, but must be set for proactive traceroutes to work.
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
IPSECTunnelDeleteResponse { deleted, deleted_ipsec_tunnel }
deleted_ipsec_tunnel: optional { id, cloudflare_endpoint, interface_address, 14 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
When true, the tunnel can use a null-cipher (ENCR_NULL) in the ESP tunnel (Phase 2).
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
custom_remote_identities: optional { fqdn_id }
A custom IKE ID of type FQDN that may be used to identity the IPsec tunnel. The generated IKE IDs can still be used even if this custom value is specified.
Must be of the form <custom label>.<account ID>.custom.ipsec.cloudflare.com.
This custom ID does not need to be unique. Two IPsec tunnels may have the same custom fqdn_id. However, if another IPsec tunnel has the same value then the two tunnels cannot have the same cloudflare_endpoint.
The IP address assigned to the customer side of the IPsec tunnel. Not required, but must be set for proactive traceroutes to work.
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
IPSECTunnelBulkUpdateResponse { modified, modified_ipsec_tunnels }
modified_ipsec_tunnels: optional array of { id, cloudflare_endpoint, interface_address, 14 more }
A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.
When true, the tunnel can use a null-cipher (ENCR_NULL) in the ESP tunnel (Phase 2).
True if automatic stateful return routing should be enabled for a tunnel, false otherwise.
bgp: optional { customer_asn, extra_prefixes, md5_key }
Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.
MD5 key to use for session authentication.
Note that this is not a security measure. MD5 is not a valid security mechanism, and the key is not treated as a secret value. This is only supported for preventing misconfiguration, not for defending against malicious attacks.
The MD5 key, if set, must be of non-zero length and consist only of the following types of character:
- ASCII alphanumerics:
[a-zA-Z0-9] - Special characters in the set
'!@#$%^&*()+[]{}<>/.,;:_-~= |`
In other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),
quotation mark ("), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed
(0x0C), and the question mark (?). Requests specifying an MD5 key with one or more of
these disallowed characters will be rejected.
bgp_status: optional { state, tcp_established, updated_at, 5 more }
custom_remote_identities: optional { fqdn_id }
A custom IKE ID of type FQDN that may be used to identity the IPsec tunnel. The generated IKE IDs can still be used even if this custom value is specified.
Must be of the form <custom label>.<account ID>.custom.ipsec.cloudflare.com.
This custom ID does not need to be unique. Two IPsec tunnels may have the same custom fqdn_id. However, if another IPsec tunnel has the same value then the two tunnels cannot have the same cloudflare_endpoint.
The IP address assigned to the customer side of the IPsec tunnel. Not required, but must be set for proactive traceroutes to work.
health_check: optional { direction, enabled, rate, 2 more }
direction: optional "unidirectional" or "bidirectional"The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.
target: optional { effective, saved } or stringThe destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.
MagicHealthCheckTarget { effective, saved } The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to customer_gre_endpoint address. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.
A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127
Magic TransitRoutes
List Routes
Route Details
Create a Route
Update Route
Delete Route
Update Many Routes
Delete Many Routes
ModelsExpand Collapse
Magic TransitSites
List Sites
Site Details
Create a new Site
Update Site
Patch Site
Delete Site
Magic TransitSitesApp Configuration
List App Configs
Create a new App Config
Update an App Config
Update an App Config
Delete App Config
ModelsExpand Collapse
AppConfigurationListResponse = { account_app_id, id, breakout, 3 more } or { managed_app_id, id, breakout, 3 more } Traffic decision configuration for an app.
Traffic decision configuration for an app.
AccountApp { account_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
ManagedApp { managed_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
AppConfigurationCreateResponse = { account_app_id, id, breakout, 3 more } or { managed_app_id, id, breakout, 3 more } Traffic decision configuration for an app.
Traffic decision configuration for an app.
AccountApp { account_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
ManagedApp { managed_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
AppConfigurationUpdateResponse = { account_app_id, id, breakout, 3 more } or { managed_app_id, id, breakout, 3 more } Traffic decision configuration for an app.
Traffic decision configuration for an app.
AccountApp { account_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
ManagedApp { managed_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
AppConfigurationEditResponse = { account_app_id, id, breakout, 3 more } or { managed_app_id, id, breakout, 3 more } Traffic decision configuration for an app.
Traffic decision configuration for an app.
AccountApp { account_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
ManagedApp { managed_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
AppConfigurationDeleteResponse = { account_app_id, id, breakout, 3 more } or { managed_app_id, id, breakout, 3 more } Traffic decision configuration for an app.
Traffic decision configuration for an app.
AccountApp { account_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
ManagedApp { managed_app_id, id, breakout, 3 more }
Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.
WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).
Magic TransitSitesACLs
List Site ACLs
Site ACL Details
Create a new Site ACL
Update Site ACL
Patch Site ACL
Delete Site ACL
ModelsExpand Collapse
ACL { id, description, forward_locally, 5 more } Bidirectional ACL policy for network traffic within a site.
Bidirectional ACL policy for network traffic within a site.
ACLConfiguration { lan_id, lan_name, port_ranges, 2 more }
Array of port ranges on the provided LAN that will be included in the ACL. If no ports or port rangess are provided, communication on any port on this LAN is allowed.
Array of ports on the provided LAN that will be included in the ACL. If no ports or port ranges are provided, communication on any port on this LAN is allowed.
Magic TransitSitesLANs
List Site LANs
Site LAN Details
Create a new Site LAN
Update Site LAN
Patch Site LAN
Delete Site LAN
ModelsExpand Collapse
LAN { id, bond_id, ha_link, 9 more }
mark true to use this LAN for HA probing. only works for site with HA turned on. only one LAN can be set as the ha_link.
Magic TransitSitesWANs
List Site WANs
Site WAN Details
Create a new Site WAN
Update Site WAN
Patch Site WAN
Delete Site WAN
ModelsExpand Collapse
Magic TransitConnectors
List Connectors
Fetch Connector
Add a connector to your account
Replace Connector or Re-provision License Key
Edit Connector to update specific properties or Re-provision License Key
Remove a connector from your account
ModelsExpand Collapse
ConnectorListResponse { id, activated, interrupt_window_days_of_week, 10 more }
ConnectorGetResponse { id, activated, interrupt_window_days_of_week, 10 more }
ConnectorCreateResponse { id, activated, interrupt_window_days_of_week, 10 more }
ConnectorUpdateResponse { id, activated, interrupt_window_days_of_week, 10 more }
ConnectorEditResponse { id, activated, interrupt_window_days_of_week, 10 more }
ConnectorDeleteResponse { id, activated, interrupt_window_days_of_week, 10 more }
Magic TransitConnectorsEvents
List Events
Get Event
Magic TransitConnectorsEventsLatest
Get latest Events
Magic TransitConnectorsSnapshots
List Snapshots
Get Snapshot
ModelsExpand Collapse
SnapshotGetResponse { count_reclaim_failures, count_reclaimed_paths, count_record_failed, 170 more } Snapshot
Snapshot
Numeric value associated with high availability state (0 = disabled, 1 = active, 2 = standby, 3 = stopped, 4 = fault)
interfaces: optional array of { name, operstate, ip_addresses, speed }
Percentage of time over a 10 second window that all tasks were stalled
Percentage of time over a 5 minute window that all tasks were stalled
Percentage of time over a 1 minute window that all tasks were stalled
Percentage of time over a 10 second window that some tasks were stalled
Percentage of time over a 3 minute window that some tasks were stalled
Percentage of time over a 1 minute window that some tasks were stalled
Number of kernel scheduling entities that currently exist on the system
Non-file backed huge pages mapped into user-space page tables
Estimate of how much memory is available for starting new applications
Total amount of memory currently available to be allocated on the system
The number of huge pages in the pool that are not yet allocated
Number of huge pages for which a commitment has been made, but no allocation has yet been made
Kernel allocations that the kernel will attempt to reclaim under memory pressure
Amount of memory dedicated to the lowest level of page tables
Memory allocated to the per-cpu alloctor used to back per-cpu allocations
Percentage of time over a 10 second window that all tasks were stalled
Percentage of time over a 5 minute window that all tasks were stalled
Percentage of time over a 1 minute window that all tasks were stalled
Percentage of time over a 10 second window that some tasks were stalled
Percentage of time over a 5 minute window that some tasks were stalled
Percentage of time over a 1 minute window that some tasks were stalled
Amount of memory dedicated to the lowest level of page tables
Memory used by shmem and tmpfs, allocated with huge pages
Number of ICMP messages which this entity did not send due to ICMP-specific errors
Number of input datagrams discarded due to errors in the IP address
Number of input datagrams successfully delivered to IP user-protocols
Number of input datagrams discarded due to errors in the IP header
Number of input datagrams discarded due unknown or unsupported protocol
Number of seconds fragments are held while awaiting reassembly
Number of times TCP transitions to CLOSED from SYN-SENT or SYN-RCVD, plus transitions to LISTEN from SYN-RCVD
Number of times TCP transitions to CLOSED from ESTABLISHED or CLOSE-WAIT
Maximum value permitted by a TCP implementation for the retransmission timeout (milliseconds)
Minimum value permitted by a TCP implementation for the retransmission timeout (milliseconds)
Number of UDP datagrams failed to be delivered for reasons other than lack of application at the destination port
Number of UDP datagrams received for which there was not application at the destination port
Magic TransitConnectorsSnapshotsLatest
Get latest Snapshots
ModelsExpand Collapse
LatestListResponse { count, items }
items: array of { count_reclaim_failures, count_reclaimed_paths, count_record_failed, 170 more }
Numeric value associated with high availability state (0 = disabled, 1 = active, 2 = standby, 3 = stopped, 4 = fault)
interfaces: optional array of { name, operstate, ip_addresses, speed }
Percentage of time over a 10 second window that all tasks were stalled
Percentage of time over a 5 minute window that all tasks were stalled
Percentage of time over a 1 minute window that all tasks were stalled
Percentage of time over a 10 second window that some tasks were stalled
Percentage of time over a 3 minute window that some tasks were stalled
Percentage of time over a 1 minute window that some tasks were stalled
Number of kernel scheduling entities that currently exist on the system
Non-file backed huge pages mapped into user-space page tables
Estimate of how much memory is available for starting new applications
Total amount of memory currently available to be allocated on the system
The number of huge pages in the pool that are not yet allocated
Number of huge pages for which a commitment has been made, but no allocation has yet been made
Kernel allocations that the kernel will attempt to reclaim under memory pressure
Amount of memory dedicated to the lowest level of page tables
Memory allocated to the per-cpu alloctor used to back per-cpu allocations
Percentage of time over a 10 second window that all tasks were stalled
Percentage of time over a 5 minute window that all tasks were stalled
Percentage of time over a 1 minute window that all tasks were stalled
Percentage of time over a 10 second window that some tasks were stalled
Percentage of time over a 5 minute window that some tasks were stalled
Percentage of time over a 1 minute window that some tasks were stalled
Amount of memory dedicated to the lowest level of page tables
Memory used by shmem and tmpfs, allocated with huge pages
Number of ICMP messages which this entity did not send due to ICMP-specific errors
Number of input datagrams discarded due to errors in the IP address
Number of input datagrams successfully delivered to IP user-protocols
Number of input datagrams discarded due to errors in the IP header
Number of input datagrams discarded due unknown or unsupported protocol
Number of seconds fragments are held while awaiting reassembly
Number of times TCP transitions to CLOSED from SYN-SENT or SYN-RCVD, plus transitions to LISTEN from SYN-RCVD
Number of times TCP transitions to CLOSED from ESTABLISHED or CLOSE-WAIT
Maximum value permitted by a TCP implementation for the retransmission timeout (milliseconds)
Minimum value permitted by a TCP implementation for the retransmission timeout (milliseconds)
Number of UDP datagrams failed to be delivered for reasons other than lack of application at the destination port
Number of UDP datagrams received for which there was not application at the destination port
Magic TransitPCAPs
List packet capture requests
Get PCAP request
Create PCAP request
Stop full PCAP
ModelsExpand Collapse
PCAP { id, filter_v1, offset_time, 5 more }
The RFC 3339 offset timestamp from which to query backwards for packets. Must be within the last 24h. When this field is empty, defaults to time of request.
PCAPListResponse = PCAP { id, filter_v1, offset_time, 5 more } or { id, byte_limit, colo_name, 10 more }
PCAP { id, filter_v1, offset_time, 5 more }
The RFC 3339 offset timestamp from which to query backwards for packets. Must be within the last 24h. When this field is empty, defaults to time of request.
MagicVisibilityPCAPsPCAPsResponseFull { id, byte_limit, colo_name, 10 more }
The maximum number of bytes to capture. This field only applies to full packet captures.
The name of the data center used for the packet capture. This can be a specific colo (ord02) or a multi-colo name (ORD). This field only applies to full packet captures.
The full URI for the bucket. This field only applies to full packet captures.
An error message that describes why the packet capture failed. This field only applies to full packet captures.
status: optional "unknown" or "success" or "pending" or 5 moreThe status of the packet capture request.
The status of the packet capture request.
PCAPGetResponse = PCAP { id, filter_v1, offset_time, 5 more } or { id, byte_limit, colo_name, 10 more }
PCAP { id, filter_v1, offset_time, 5 more }
The RFC 3339 offset timestamp from which to query backwards for packets. Must be within the last 24h. When this field is empty, defaults to time of request.
MagicVisibilityPCAPsPCAPsResponseFull { id, byte_limit, colo_name, 10 more }
The maximum number of bytes to capture. This field only applies to full packet captures.
The name of the data center used for the packet capture. This can be a specific colo (ord02) or a multi-colo name (ORD). This field only applies to full packet captures.
The full URI for the bucket. This field only applies to full packet captures.
An error message that describes why the packet capture failed. This field only applies to full packet captures.
status: optional "unknown" or "success" or "pending" or 5 moreThe status of the packet capture request.
The status of the packet capture request.
PCAPCreateResponse = PCAP { id, filter_v1, offset_time, 5 more } or { id, byte_limit, colo_name, 10 more }
PCAP { id, filter_v1, offset_time, 5 more }
The RFC 3339 offset timestamp from which to query backwards for packets. Must be within the last 24h. When this field is empty, defaults to time of request.
MagicVisibilityPCAPsPCAPsResponseFull { id, byte_limit, colo_name, 10 more }
The maximum number of bytes to capture. This field only applies to full packet captures.
The name of the data center used for the packet capture. This can be a specific colo (ord02) or a multi-colo name (ORD). This field only applies to full packet captures.
The full URI for the bucket. This field only applies to full packet captures.
An error message that describes why the packet capture failed. This field only applies to full packet captures.
status: optional "unknown" or "success" or "pending" or 5 moreThe status of the packet capture request.
The status of the packet capture request.