API Reference

CSD has a dedicated API at /api/shape/csd/ for managing domains, scripts, mitigation, and monitoring. CSD can also be enabled on HTTP Load Balancers via the load balancer configuration API.

Authentication

All API calls require an API token. Generate one in the XC Console under Administration → Credentials → API Credentials.

Set up your environment variables as described in API Automation — Environment Setup:

set -a && source .env && set +a

All curl examples use the xTOKENx placeholder format. Substitute with your environment variables or use the interactive form at the top of the page. For example, xF5XC_API_TOKENx corresponds to $F5XC_API_TOKEN.

-H "Authorization: APIToken xF5XC_API_TOKENx"

API Conventions

Note

These conventions apply to all F5 Distributed Cloud (F5 XC) configuration and CSD API endpoints. Understanding them prevents common automation mistakes.

Response Bodies

• POST returns the created object as JSON.
• PUT and DELETE return an empty \{\} on HTTP 200 — this is normal, not an error. Do not treat an empty response body as a failure.

List vs GET Endpoints

List endpoints (e.g., /healthchecks, /origin_pools, /protected_domains) and individual GET endpoints (e.g., /healthchecks/\{name\}) return different response structures:

Endpoint type	Example path	Response structure
List	/origin_pools	Items have top-level .name, .namespace, .tenant with metadata: null and get_spec: null
Individual GET	/origin_pools/\{name\}	Object has .metadata.name, .spec.* with full configuration

Use the correct jq paths for each. For example, to extract names from a list endpoint use .items[].name, not .items[].metadata.name.

Protected Domain Identifier

For protected domain GET and DELETE operations, the \{name\} path parameter is the domain value itself (e.g., bankexample.com), not an arbitrary object name. This differs from other F5 XC objects where the name is a user-chosen identifier.

CSD API Endpoints

Base path: /api/shape/csd/namespaces/\{namespace\}/

Status and Initialization

Operation	Method	Path
Enable CSD	POST	/api/shape/csd/namespaces/system/init
Get Status	GET	/api/shape/csd/namespaces/\{namespace\}/status
Get JS Configuration	GET	/api/shape/csd/namespaces/\{namespace\}/js_configuration
Test JS	POST	/api/shape/csd/namespaces/\{namespace\}/testjs
Update Domains	POST	/api/shape/csd/namespaces/\{namespace\}/update_domains

Protected Domains

Operation	Method	Path
List	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Get	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}
Create	POST	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Delete	DELETE	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}

Detected Domains

Operation	Method	Path
List Detected	GET	/api/shape/csd/namespaces/\{namespace\}/detected_domains
Get Details	GET	/api/shape/csd/namespaces/\{namespace\}/domain_details

Allowed Domains

Operation	Method	Path
List	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Get	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}
Create	POST	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Delete	DELETE	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}

Mitigated Domains

Operation	Method	Path
List	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Get	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}
Create	POST	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Delete	DELETE	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}

Scripts

Operation	Method	Path
List Scripts	POST	/api/shape/csd/namespaces/\{namespace\}/scripts
List Scripts (legacy)	GET	/api/shape/csd/namespaces/\{namespace\}/scripts
Get Script Overview	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/dashboard
List Behaviors	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/behaviors
List Network Interactions	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/networkInteractions
Update Justification	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/justification
Delete Justification	DELETE	/api/shape/csd/namespaces/\{namespace\}/script/justification/\{justification_id\}
Update Read Status	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/readStatus
List Affected Users	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/affectedUsers

Form Fields

Operation	Method	Path
List Form Fields	GET	/api/shape/csd/namespaces/\{namespace\}/formFields
List Form Fields (POST)	POST	/api/shape/csd/namespaces/\{namespace\}/formFields
Get Form Field	GET	/api/shape/csd/namespaces/\{namespace\}/formFields/\{id\}
List by Script	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/formFields
Update Field Analysis	POST	/api/shape/csd/namespaces/\{namespace\}/formFields/analysis

Enable CSD

Initialize CSD for the tenant:

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/system/init"

Get CSD Status

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/status" \
  | jq .

Protected Domains

List Protected Domains

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains" \
  | jq .

Add a Protected Domain

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "my-app",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains" \
  | jq .

Delete a Protected Domain

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains/my-app"

Detected Domains

List Detected Domains

Query parameters: locations (filter by location), risk (filter by risk level).

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/detected_domains" \
  | jq .

Filter by high risk:

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/detected_domains?risk=high" \
  | jq .

Get Domain Details

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/domain_details?name=suspicious.example.com" \
  | jq .

Scripts

List All Scripts

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts" \
  | jq .

Get Script Overview

SCRIPT_ID="your-script-id"

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/dashboard" \
  | jq .

List Script Behaviors

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/behaviors" \
  | jq .

List Network Interactions

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/networkInteractions" \
  | jq .

Mitigation

Add a Mitigated Domain

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "blocked-domain",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains" \
  | jq .

List Mitigated Domains

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains" \
  | jq .

Remove Mitigation

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains/blocked-domain"

Allowed Domains

Add an Allowed Domain

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "trusted-cdn",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains" \
  | jq .

List Allowed Domains

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains" \
  | jq .

Remove an Allowed Domain

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains/trusted-cdn"

JS Injection Configuration

Get Current Configuration

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/js_configuration" \
  | jq .

HTTP Load Balancer CSD Configuration

CSD JavaScript injection can also be enabled directly on an HTTP Load Balancer via the configuration API at /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\}.

The client_side_defense field within the load balancer spec controls injection:

{
  "client_side_defense": {
    "policy": {
      "js_insert_all_pages": {}
    }
  }
}

The policy accepts one of:

Field	Description
js_insert_all_pages	Inject on all pages
js_insert_all_pages_except	Inject on all pages except exclusion rules
js_insertion_rules	Inject only on pages matching rules
disable_js_insert	Do not inject

To disable CSD on a load balancer, replace client_side_defense with disable_client_side_defense: \{\}.

Read CSD Configuration from Load Balancer

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  | jq '.spec.client_side_defense'

Enable CSD on a Load Balancer

Retrieve, modify, and apply:

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  > lb-config.json

jq '.spec |= (
  del(.disable_client_side_defense) |
  .client_side_defense = {
    "policy": {
      "js_insert_all_pages": {}
    }
  }
)' lb-config.json > lb-config-updated.json

curl -s -X PUT \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d @lb-config-updated.json \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  | jq '.spec.client_side_defense'

Domain and Path Matching for Exclusion Rules

When using js_insert_all_pages_except or js_insertion_rules, each rule matches a domain and path combination.

Domain (choose one):

Field	Example
any_domain: \{\}	All domains
domain.exact_value	"app.example.com"
domain.suffix_value	".example.com"
domain.regex_value	".*\\.example\\.com"

Path (choose one):

Field	Example
path.path	"/login"
path.prefix	"/checkout"
path.regex	"/user/[0-9]+"

API Reference

• CSD API Reference — Full endpoint documentation
• Configure CSD — Console configuration guide
• API Credentials — Generate API tokens