Cloud Diversion

Cloud Diversion

Overview

Cloud Diversion OpenAPI provides Site and Network Group discovery, atomic Policy updates, and manual divert operations for individual networks in a target Customer’s Origin Protection resources.

Supported Policy modes depend on the resource:

Site Policy does not support manual divert. When Network Group Custom is off, the parent Site Policy applies and the Group’s saved Policy is retained.

Version information

Version : 1.0.0.BETA

URI scheme

Host : {your_basic_domain} BasePath : /api Schemes : HTTPS

Paths

List Cloud Diversion sites for a customer.

GET /spe/common/customer/{customer_id}/diversion/sites

Description

Returns only Origin Protection Sites that have joined Cloud Diversion for the target Customer. Results use one address family per response, have a fixed ascending creation-time and stable-ID order, and can be filtered by an exact canonical Protected Network CIDR. The response never includes an internal goa_site_id or a Site CIDR collection.

Parameters

Responses

Cloud Diversion Site List Result

Site item

Notes

• The path customer_id determines the Customer whose Sites are listed; it is also verified by the Cloud Diversion App.
• Omitting ip_version uses IPv4. An IPv6 CIDR therefore requires ip_version=ipv6.
• CIDR matching is exact after normalization. It does not match a parent, child, or contained IP address.
• Supporting configuration IDs are opaque strings and must not be treated as numbers.

Atomically update a Cloud Diversion Site Policy for a customer.

POST /spe/common/customer/{customer_id}/diversion/sites/{site_id}/policy

Uses application/json and accepts only detection_enabled (JSON boolean) and diversion_mode (off, monitor, or auto_divert). The body cannot be empty; null, unknown fields, string/number booleans, and invalid enums are rejected. Supplying detection_enabled requires diversion_mode; diversion_mode alone is allowed only when compatible with the current Detection state.

The encrypted path customer_id selects the target Customer and is decrypted by Open API Service. Cloud Diversion App independently verifies that the public site_id belongs to that Customer. Site targets are limited to Detection OFF + off, or Detection ON + monitor/auto_divert. Saved Detection Template, Diversion Scope, Route Template and Peer Group references are retained and validated. A repeated target succeeds without another downstream operation or audit record.

{"detection_enabled": true, "diversion_mode": "monitor"}

Success returns { "code": 0, "msg": "Success.", "result": null }. It means the configuration was accepted and saved, not that traffic switching has completed; no operation ID or transition status is returned. Actual changes are audited as openapi with source spe_admin_api. Business errors use HTTP 200 with a nonzero code; malformed request values use 40058603; unavailable or invalid upstream responses use 502 with msg: "upstream_unavailable".

List Cloud Diversion Network Groups for a customer Site.

GET /spe/common/customer/{customer_id}/diversion/sites/{site_id}/network-groups

Returns paginated Network Groups below the target Customer’s public Site ID. customer_id is encrypted and decrypted by Open API Service; Cloud Diversion App independently validates Customer, Site and Network Group ownership. cidr is normalized and performs exact Protected Network member matching only; it must use the address family of the parent Site. The endpoint does not accept ip_version.

Each item exposes opaque network_group_id, name, description, custom_enabled, the Network Group’s own saved policy, normalized networks, and network_count. It never synthesizes effective_policy, custom_policy, or effective_policy_source; when Custom is off, read the parent Site Policy to determine inherited behavior. Omitted query values use page=1 and page_size=20; page_size is at most 100. No match or a page beyond the final page returns successful empty items with correct pagination metadata.

The saved Network Group policy.diversion_mode supports off, divert, monitor, and auto_divert, including when Custom is off. Site Policy supports only off, monitor, and auto_divert.

Parameters

Response

{
  "code": 0,
  "msg": "Success.",
  "result": {
    "items": [{
      "network_group_id": "201887692295201",
      "name": "production",
      "description": "Production networks",
      "custom_enabled": false,
      "policy": {"detection_enabled": true, "diversion_mode": "auto_divert"},
      "networks": ["203.0.113.0/24"],
      "network_count": 1
    }],
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1
  }
}

The response always uses code, msg, and result. Parameter errors use 40058603; Customer/Site/group ownership and resource errors retain their App business code under HTTP 200; unavailable, empty, or invalid App responses use 502 and upstream_unavailable.

Atomically update a Cloud Diversion Network Group Policy for a customer.

POST /spe/common/customer/{customer_id}/diversion/sites/{site_id}/network-groups/{network_group_id}/policy

Uses application/json and accepts only custom_enabled, detection_enabled (both JSON booleans), and diversion_mode (off, divert, monitor, or auto_divert). The body cannot be empty; null, unknown fields, string/number booleans, and invalid enums are rejected. Supplying detection_enabled requires diversion_mode; diversion_mode alone is allowed only when compatible with the current Detection state.

The encrypted path customer_id selects the target Customer and is decrypted by Open API Service. Cloud Diversion App independently verifies that the Customer owns the public site_id, that the opaque network_group_id exists, and that the Network Group belongs to that Site before any write.

With Custom enabled, valid targets are Detection OFF + off/divert, or Detection ON + monitor/auto_divert. Turning Custom off accepts only custom_enabled, preserves the Network Group’s saved Policy, and makes the parent Site Policy effective. While Custom remains off, Detection and Diversion Mode cannot be modified. Turning Custom on restores the saved Policy; the same request may include a legal Detection/Diversion target.

Saved Detection Template, Diversion Scope, Route Template, and Peer Group references are retained and validated. A repeated target succeeds without another Network operation or audit record. Actual changes retain Network-level audit entries with actor openapi and source spe_admin_api.

{"custom_enabled": true, "detection_enabled": false, "diversion_mode": "divert"}

Success returns { "code": 0, "msg": "Success.", "result": null }. It means the configuration was accepted and saved, not that traffic switching has completed; no operation ID or transition status is returned. Business errors use HTTP 200 with a nonzero code; malformed request values use 40058603; unavailable or invalid upstream responses use 502 with msg: "upstream_unavailable".

Start manual divert for a network.

POST /spe/common/customer/{customer_id}/diversion/divert

Description

Starts manual divert for one Origin Protection network. The network must be an IPv4 /24 or IPv6 /48 network CIDR and must belong to the target customer. Valid IPv6 input is normalized to lowercase compressed form. The request enters the Cloud Diversion workflow asynchronously.

Parameters

Consumes

• multipart/form-data

Request example

# IPv4
network=203.0.113.0/24

# IPv6
network=2001:0DB8:1234:0000:0000:0000:0000:0000/48

Responses

Stop active divert for a network.

POST /spe/common/customer/{customer_id}/diversion/divert/stop

Description

Stops the active divert for one Origin Protection network. Manual divert follows the existing Cloud Diversion policy stop behavior. Auto divert stops the current ongoing event only and does not disable Auto Divert or Auto Monitor configuration.

Parameters

Consumes

• multipart/form-data

Request example

# IPv4
network=203.0.113.0/24

# IPv6
network=2001:db8:1234::/48

Responses

Get divert status for a network.

GET /spe/common/customer/{customer_id}/diversion/divert/status?network=203.0.113.0/24
GET /spe/common/customer/{customer_id}/diversion/divert/status?network=2001:db8:1234::/48

Description

Returns the current manual or auto divert status for one Origin Protection network.

Parameters

Responses

Cloud Diversion Result

IPv6 start or stop success example

{
  "code": 0,
  "msg": "Success.",
  "result": {
    "network": "2001:db8:1234::/48"
  }
}

IPv6 status success example

{
  "code": 0,
  "msg": "Success.",
  "result": {
    "network": "2001:db8:1234::/48",
    "status": "manual_in_progress"
  }
}

Stop no active divert example

{
  "code": 0,
  "msg": "No active divert."
}

Error example

{
  "code": 40058603,
  "msg": "network must be canonical IPv4 /24 or IPv6 /48 CIDR."
}

Error Codes

Notes

• Only IPv4 /24 and IPv6 /48 network CIDR values are supported. IPv6 input may use compressed or expanded notation and is returned in lowercase compressed form.
• The CIDR must belong to the target customer. Requests for CIDRs outside the customer scope are rejected without exposing other customer resources.
• Start requires the target network to use custom policy.
• Start switches the target network to manual divert and sets detection mode to off.
• Stop switches manual divert to off. For Auto Divert or Auto Monitor events, stop only ends the current ongoing event and does not disable Auto Divert or Auto Monitor configuration.
• The API does not support operation_id or idempotency_key in this version.
• A successful start response means the request has entered the Cloud Diversion control workflow; it does not guarantee immediate route convergence. Use the status API or event list to confirm the current divert state.