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.

Choose one resource owner

The API-managed workflow and the Terraform-managed workflow create the same logical architecture, but they are mutually exclusive ownership modes. Choose one ownership mode. Never run the API create/update/delete workflow against resources present in Terraform state. API GET and list calls remain safe for inspection.

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, xXCSH_API_TOKENx corresponds to $XCSH_API_TOKEN.

-H "Authorization: APIToken xXCSH_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 and PUT return the created or replaced resource when defined by the endpoint schema.
• DELETE returns an object response; an empty \{\} on HTTP 200 is a normal success response for standard configuration deletes.

List vs GET Endpoints

List endpoints (for example, /origin_pools) return an items collection. Individual GET endpoints (for example, /origin_pools/\{name\}) return the selected resource with its full configuration. Use the response shape documented for the exact endpoint rather than assuming list and individual responses are interchangeable.

Protected Domain Identifiers

A protected-domain object has two distinct identifiers:

• metadata.name is the DNS-label resource name used by individual GET and DELETE paths. The reference deployment uses client-side-defense.
• spec.protected_domain is the registrable domain monitored by CSD. The reference deployment uses f5-sales-demo.com, which covers client-side-defense.f5-sales-demo.com.

Do not place the FQDN in the path unless it is also the object’s actual metadata.name.

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
Get Summary	GET	/api/shape/csd/namespaces/\{namespace\}/summary
Bulk Delete Domains	DELETE	/api/shape/csd/namespaces/\{namespace\}/domains
Create Report	POST	/api/shape/csd/namespaces/\{namespace\}/reports
List Report History	GET	/api/shape/csd/namespaces/\{namespace\}/reports-history
Download Report	GET	/api/shape/csd/namespaces/\{namespace\}/reports/metadata/\{job_id\}/download

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
List Detected (POST)	POST	/api/shape/csd/namespaces/\{namespace\}/detectedDomains
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
Get Scripts Overview	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/overview
List Scripts (GET)	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
Update Approval Status	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/approval-status
List Inline Scripts	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/inline

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 xXCSH_API_TOKENx" \
  -H "Content-Type: application/json" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/system/init"

Get CSD Status

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/status" \
  | jq .

Protected Domain Examples

List Protected Domains

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/protected_domains" \
  | jq .

Add a Protected Domain

curl -s -X POST \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "client-side-defense",
      "namespace": "xXCSH_NAMESPACEx"
    },
    "spec": {
      "protected_domain": "f5-sales-demo.com"
    }
  }' \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/protected_domains" \
  | jq .

Delete a Protected Domain

Do not issue a standalone DELETE from this reference. Use the guarded Phase 4 API teardown, which:

1. validates the session ledger against the normalized active XCSH_API_URL, tenant identity, namespace, and domain;
2. derives the target only from the unique protected-domain entry marked created by the current session;
3. requires explicit destructive approval before deletion; and
4. deletes in reverse dependency order and verifies the exact protected domain returns 404.

A protected domain that is pre-existing, unknown, recorded by another session, or owned by Terraform is not a deletion target.

Detected Domain Examples

List Detected Domains

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

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/detected_domains" \
  | jq .

Filter by high risk:

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/detected_domains?risk=high" \
  | jq .

Get Domain Details

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

Script Examples

List All Scripts

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

Get Script Overview

SCRIPT_ID="your-script-id"

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/scripts/${SCRIPT_ID}/dashboard" \
  | jq .

List Script Behaviors

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/scripts/${SCRIPT_ID}/behaviors" \
  | jq .

List Network Interactions

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/scripts/${SCRIPT_ID}/networkInteractions" \
  | jq .

Mitigation

Add a Mitigated Domain

curl -sS -X POST \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "suspicious-example-com",
      "namespace": "xXCSH_NAMESPACEx"
    },
    "spec": {
      "mitigated_domain": "suspicious.example.com"
    }
  }' \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/mitigated_domains" \
  | jq .

List Mitigated Domains

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/mitigated_domains" \
  | jq .

Remove Mitigation

curl -s -X DELETE \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/mitigated_domains/suspicious-example-com"

Allowed Domain Examples

Add an Allowed Domain

curl -sS -X POST \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "cdn-example-com",
      "namespace": "xXCSH_NAMESPACEx"
    },
    "spec": {
      "allowed_domain": "cdn.example.com"
    }
  }' \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/allowed_domains" \
  | jq .

List Allowed Domains

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/allowed_domains" \
  | jq .

Remove an Allowed Domain

curl -s -X DELETE \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_NAMESPACEx/allowed_domains/cdn-example-com"

JS Injection Configuration

Get Current Configuration

curl -s \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/shape/csd/namespaces/xXCSH_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 reference architecture uses one unsuffixed load balancer named client-side-defense in namespace client-side-defense. It serves client-side-defense.f5-sales-demo.com with automatic HTTPS, HTTP-to-HTTPS redirect, a public default VIP, one origin-pool reference, and all-pages CSD insertion.

The AWS origin pool uses public_name.dns_name with the ALB hostname. The separate Azure alternate uses public_ip.ip.

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 -fsS \
  -H "Authorization: APIToken xXCSH_API_TOKENx" \
  "xXCSH_API_URLx/api/config/namespaces/xXCSH_NAMESPACEx/http_loadbalancers/xXCSH_LB_NAMEx" \
  | jq -e '.spec.client_side_defense'

Caution

This replacement is permitted only for the exact API-owned load balancer recorded as created in the current session ledger. A pre-existing, unknown, other-session, or Terraform-owned load balancer must not be replaced through the API.

Enable CSD on a Load Balancer

Use Phase 1 — Clean Load-Balancer PUT instead of issuing a standalone PUT from this reference. The guarded replacement:

1. validates the ledger against the normalized active XCSH_API_URL, tenant identity, namespace, and domain;
2. requires exactly one matching current-session http_loadbalancer entry with status: "created";
3. builds a schema-valid replacement body containing only metadata and spec; and
4. records the PUT outcome and verifies the settled configuration.

If the exact load balancer is not owned by the current API session, stop. Inspect Terraform-owned resources with GET and make their changes through Terraform state.

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 References

• Enriched Shape API reference — CSD status, domains, scripts, reports, form fields, and mitigation endpoints
• Enriched Virtual API reference — HTTP load balancer, origin pool, and health-check endpoints
• Configure CSD — Console configuration guide
• API Credentials — Generate API tokens