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 the authenticated 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.

GET /specp/common/diversion/sites

Description

Returns only Origin Protection Sites that have joined Cloud Diversion. 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

Success example

{
  "code": 0,
  "msg": "Success.",
  "result": {
    "items": [
      {
        "site_id": "b6c9bcffa5685971",
        "site_name": "production",
        "ip_version": "ipv4",
        "policy": {
          "detection_enabled": true,
          "diversion_mode": "auto_divert",
          "detection_template": {"id": "123", "name": "Default Detection"},
          "diversion_scope": "off_net",
          "off_net_route_template": null,
          "on_net_route_template": null,
          "peer_group": null
        }
      }
    ],
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1
  }
}

Notes

• Customer identity comes from the access token; do not provide customer_id.
• 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.

List Cloud Diversion Network Groups.

GET /specp/common/diversion/sites/{site_id}/network-groups

Returns Network Groups nested under an owned public Site ID. Results use fixed ascending creation-time and opaque-ID ordering with page (default 1) and page_size (default 20, maximum 100). cidr is normalized by the service and matched only against an exact Protected Network member. Its address family is determined by the parent Site, so this endpoint does not accept ip_version. No match and a page past the end return a successful empty items array.

Each item contains opaque string network_group_id, name, description, boolean custom_enabled, normalized networks, and network_count. Networks are the only member representation returned: internal Network IDs and Network-level Policy fields are not exposed.

policy is always the Network Group’s own saved Policy, even when custom_enabled is false. It has the same fields and supporting-configuration semantics as a Site Policy: opaque string IDs, null for an unconfigured reference, and name: null when a saved reference was deleted. This endpoint never returns custom_policy, effective_policy, or effective_policy_source; read the parent Site to determine inherited behavior.

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.

{"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","detection_template":null,"diversion_scope":"off_net","off_net_route_template":null,"on_net_route_template":null,"peer_group":null},"networks":["203.0.113.0/24"],"network_count":1}],"page":1,"page_size":20,"total":1,"total_pages":1}}

Atomically update a Cloud Diversion Site Policy.

POST /specp/common/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.

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. 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".

Atomically update a Cloud Diversion Network Group Policy.

POST /specp/common/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.

Customer identity comes from the access token. The App 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 customer_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 /specp/common/diversion/divert

Description

Starts manual divert for one Origin Protection network owned by the authenticated customer. The network must be an IPv4 /24 or IPv6 /48 network CIDR. 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 /specp/common/diversion/divert/stop

Description

Stops the active divert for one Origin Protection network owned by the authenticated customer. 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 /specp/common/diversion/divert/status?network=203.0.113.0/24
GET /specp/common/diversion/divert/status?network=2001:db8:1234::/48

Description

Returns the current manual or auto divert status for one Origin Protection network owned by the authenticated customer.

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": "auto_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

• Customer API uses the authenticated customer identity; do not pass customer_id.
• 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 authenticated 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.