API Reference

Magic Transit

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Sites

List Sites

GET/accounts/{account_id}/magic/sites

Site Details

GET/accounts/{account_id}/magic/sites/{site_id}

Create a new Site

POST/accounts/{account_id}/magic/sites

Update Site

PUT/accounts/{account_id}/magic/sites/{site_id}

Patch Site

PATCH/accounts/{account_id}/magic/sites/{site_id}

Delete Site

DELETE/accounts/{account_id}/magic/sites/{site_id}

ModelsExpand Collapse

Site object { id, connector_id, description, 4 more }

id: optional string

Identifier

maxLength32

connector_id: optional string

Magic Connector identifier tag.

description: optional string

ha_mode: optional boolean

Site high availability mode. If set to true, the site can have two connectors and runs in high availability mode.

location: optional SiteLocation { lat, lon }

Location of site in latitude and longitude.

name: optional string

The name of the site.

secondary_connector_id: optional string

Magic Connector identifier tag. Used when high availability mode is on.

SiteLocation object { lat, lon }

Location of site in latitude and longitude.

lat: optional string

Latitude

lon: optional string

Longitude

SitesApp Configuration

List App Configs

GET/accounts/{account_id}/magic/sites/{site_id}/app_configs

Create a new App Config

POST/accounts/{account_id}/magic/sites/{site_id}/app_configs

Update an App Config

PUT/accounts/{account_id}/magic/sites/{site_id}/app_configs/{app_config_id}

Update an App Config

PATCH/accounts/{account_id}/magic/sites/{site_id}/app_configs/{app_config_id}

Delete App Config

DELETE/accounts/{account_id}/magic/sites/{site_id}/app_configs/{app_config_id}

ModelsExpand Collapse

AppConfigurationListResponse = object { account_app_id, id, breakout, 3 more } or object { managed_app_id, id, breakout, 3 more }

Traffic decision configuration for an app.

One of the following:

AccountApp object { account_app_id, id, breakout, 3 more }

account_app_id: string

Magic account app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

ManagedApp object { managed_app_id, id, breakout, 3 more }

managed_app_id: string

Managed app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

AppConfigurationCreateResponse = object { account_app_id, id, breakout, 3 more } or object { managed_app_id, id, breakout, 3 more }

Traffic decision configuration for an app.

One of the following:

AccountApp object { account_app_id, id, breakout, 3 more }

account_app_id: string

Magic account app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

ManagedApp object { managed_app_id, id, breakout, 3 more }

managed_app_id: string

Managed app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

AppConfigurationUpdateResponse = object { account_app_id, id, breakout, 3 more } or object { managed_app_id, id, breakout, 3 more }

Traffic decision configuration for an app.

One of the following:

AccountApp object { account_app_id, id, breakout, 3 more }

account_app_id: string

Magic account app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

ManagedApp object { managed_app_id, id, breakout, 3 more }

managed_app_id: string

Managed app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

AppConfigurationEditResponse = object { account_app_id, id, breakout, 3 more } or object { managed_app_id, id, breakout, 3 more }

Traffic decision configuration for an app.

One of the following:

AccountApp object { account_app_id, id, breakout, 3 more }

account_app_id: string

Magic account app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

ManagedApp object { managed_app_id, id, breakout, 3 more }

managed_app_id: string

Managed app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

AppConfigurationDeleteResponse = object { account_app_id, id, breakout, 3 more } or object { managed_app_id, id, breakout, 3 more }

Traffic decision configuration for an app.

One of the following:

AccountApp object { account_app_id, id, breakout, 3 more }

account_app_id: string

Magic account app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

ManagedApp object { managed_app_id, id, breakout, 3 more }

managed_app_id: string

Managed app ID.

id: optional string

Identifier

maxLength32

breakout: optional boolean

Whether to breakout traffic to the app’s endpoints directly. Null preserves default behavior.

preferred_wans: optional array of string

WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).

priority: optional number

Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)

maximum1

minimum0

site_id: optional string

Identifier

maxLength32

SitesACLs

List Site ACLs

GET/accounts/{account_id}/magic/sites/{site_id}/acls

Site ACL Details

GET/accounts/{account_id}/magic/sites/{site_id}/acls/{acl_id}

Create a new Site ACL

POST/accounts/{account_id}/magic/sites/{site_id}/acls

Update Site ACL

PUT/accounts/{account_id}/magic/sites/{site_id}/acls/{acl_id}

Patch Site ACL

PATCH/accounts/{account_id}/magic/sites/{site_id}/acls/{acl_id}

Delete Site ACL

DELETE/accounts/{account_id}/magic/sites/{site_id}/acls/{acl_id}

ModelsExpand Collapse

ACL object { id, description, forward_locally, 5 more }

Bidirectional ACL policy for network traffic within a site.

id: optional string

Identifier

maxLength32

description: optional string

Description for the ACL.

forward_locally: optional boolean

The desired forwarding action for this ACL policy. If set to “false”, the policy will forward traffic to Cloudflare. If set to “true”, the policy will forward traffic locally on the Magic Connector. If not included in request, will default to false.

lan_1: optional ACLConfiguration { lan_id, lan_name, port_ranges, 2 more }

lan_2: optional ACLConfiguration { lan_id, lan_name, port_ranges, 2 more }

name: optional string

The name of the ACL.

protocols: optional array of AllowedProtocol

One of the following:

"tcp"

"udp"

"icmp"

unidirectional: optional boolean

The desired traffic direction for this ACL policy. If set to “false”, the policy will allow bidirectional traffic. If set to “true”, the policy will only allow traffic in one direction. If not included in request, will default to false.

ACLConfiguration object { lan_id, lan_name, port_ranges, 2 more }

lan_id: string

The identifier for the LAN you want to create an ACL policy with.

lan_name: optional string

The name of the LAN based on the provided lan_id.

port_ranges: optional array of string

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.

ports: optional array of number

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.

subnets: optional array of Subnet

Array of subnet IPs within the LAN that will be included in the ACL. If no subnets are provided, communication on any subnets on this LAN are allowed.

AllowedProtocol = "tcp" or "udp" or "icmp"

Array of allowed communication protocols between configured LANs. If no protocols are provided, all protocols are allowed.

One of the following:

"tcp"

"udp"

"icmp"

Subnet = string

A valid IPv4 address.

SitesLANs

List Site LANs

GET/accounts/{account_id}/magic/sites/{site_id}/lans

Site LAN Details

GET/accounts/{account_id}/magic/sites/{site_id}/lans/{lan_id}

Create a new Site LAN

POST/accounts/{account_id}/magic/sites/{site_id}/lans

Update Site LAN

PUT/accounts/{account_id}/magic/sites/{site_id}/lans/{lan_id}

Patch Site LAN

PATCH/accounts/{account_id}/magic/sites/{site_id}/lans/{lan_id}

Delete Site LAN

DELETE/accounts/{account_id}/magic/sites/{site_id}/lans/{lan_id}

ModelsExpand Collapse

DHCPRelay object { server_addresses }

server_addresses: optional array of string

List of DHCP server IPs.

DHCPServer object { dhcp_options, dhcp_pool_end, dhcp_pool_start, 3 more }

dhcp_options: optional array of object { code, type, value }

Optional list of custom DHCP options to include in DHCP responses. Only valid when DHCP server is enabled.

code: number

DHCP option number (1-254). Options 0 and 255 are reserved by RFC 2132. Options 3, 6, and 51 are not allowed because they conflict with connector-managed configuration.

maximum254

minimum1

type: "text" or "hex" or "ip" or 3 more

The type of the option value. text: a string (max 255 bytes). hex: colon-separated hex bytes (e.g. “01:04:aa:bb:cc”, max 255 bytes). ip: an IPv4 address (e.g. “10.20.30.40”). byte: an unsigned integer 0-255 (1 byte). short: an unsigned integer 0-65535 (2 bytes). integer: an unsigned integer 0-4294967295 (4 bytes).

One of the following:

"text"

"hex"

"ip"

"byte"

"short"

"integer"

value: string

The option value, interpreted according to the type field.

dhcp_pool_end: optional string

A valid IPv4 address.

dhcp_pool_start: optional string

A valid IPv4 address.

dns_server: optional string

A valid IPv4 address.

dns_servers: optional array of string

reservations: optional map[string]

Mapping of MAC addresses to IP addresses

LAN object { id, bond_id, ha_link, 9 more }

id: optional string

Identifier

maxLength32

bond_id: optional number

ha_link: optional boolean

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.

is_breakout: optional boolean

mark true to use this LAN for source-based breakout traffic

is_prioritized: optional boolean

mark true to use this LAN for source-based prioritized traffic

name: optional string

nat: optional Nat { static_prefix }

physport: optional number

routed_subnets: optional array of RoutedSubnet { next_hop, prefix, nat }

next_hop: string

A valid IPv4 address.

prefix: string

A valid CIDR notation representing an IP range.

nat: optional Nat { static_prefix }

site_id: optional string

Identifier

maxLength32

static_addressing: optional LANStaticAddressing { address, dhcp_relay, dhcp_server, 2 more }

If the site is not configured in high availability mode, this configuration is optional (if omitted, use DHCP). However, if in high availability mode, static_address is required along with secondary and virtual address.

vlan_tag: optional number

VLAN ID. Use zero for untagged.

LANStaticAddressing object { address, dhcp_relay, dhcp_server, 2 more }

If the site is not configured in high availability mode, this configuration is optional (if omitted, use DHCP). However, if in high availability mode, static_address is required along with secondary and virtual address.

address: string

A valid CIDR notation representing an IP range.

dhcp_relay: optional DHCPRelay { server_addresses }

dhcp_server: optional DHCPServer { dhcp_options, dhcp_pool_end, dhcp_pool_start, 3 more }

secondary_address: optional string

A valid CIDR notation representing an IP range.

virtual_address: optional string

A valid CIDR notation representing an IP range.

Nat object { static_prefix }

static_prefix: optional string

A valid CIDR notation representing an IP range.

RoutedSubnet object { next_hop, prefix, nat }

next_hop: string

A valid IPv4 address.

prefix: string

A valid CIDR notation representing an IP range.

nat: optional Nat { static_prefix }

SitesWANs

List Site WANs

GET/accounts/{account_id}/magic/sites/{site_id}/wans

Site WAN Details

GET/accounts/{account_id}/magic/sites/{site_id}/wans/{wan_id}

Create a new Site WAN

POST/accounts/{account_id}/magic/sites/{site_id}/wans

Update Site WAN

PUT/accounts/{account_id}/magic/sites/{site_id}/wans/{wan_id}

Patch Site WAN

PATCH/accounts/{account_id}/magic/sites/{site_id}/wans/{wan_id}

Delete Site WAN

DELETE/accounts/{account_id}/magic/sites/{site_id}/wans/{wan_id}

ModelsExpand Collapse

WAN object { id, health_check_rate, name, 5 more }

id: optional string

Identifier

maxLength32

health_check_rate: optional "low" or "mid" or "high"

Magic WAN health check rate for tunnels created on this link. The default value is mid.

One of the following:

"low"

"mid"

"high"

name: optional string

physport: optional number

priority: optional number

Priority of WAN for traffic loadbalancing.

site_id: optional string

Identifier

maxLength32

static_addressing: optional WANStaticAddressing { address, gateway_address, secondary_address }

(optional) if omitted, use DHCP. Submit secondary_address when site is in high availability mode.

vlan_tag: optional number

VLAN ID. Use zero for untagged.

WANStaticAddressing object { address, gateway_address, secondary_address }

(optional) if omitted, use DHCP. Submit secondary_address when site is in high availability mode.

address: string

A valid CIDR notation representing an IP range.

gateway_address: string

A valid IPv4 address.

secondary_address: optional string

A valid CIDR notation representing an IP range.