Operation details
GET /v1/edge-scripts
List edge scripts
- operationId
listEdgeScripts- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.read. Tenant identities only. enabled is true when module.edge_script is granted and a valid package has limits.edge_script; when false the console hides the menu and the script rule action (existing scripts stay readable).
Responses
listEdgeScripts Responses| Status | Description |
|---|
200 | Scripts by name. Fields：items: array<EdgeScript> enabled: boolean |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
503 | Edge scripts or their entitlement are unavailable (edge_scripts_unavailable). |
|---|
What to do on failure
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/edge-scripts
Create an edge script
- operationId
createEdgeScript- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.manage; tenant only; module.edge_script and limits.edge_script (403 entitlement_feature_denied / package_feature_denied). Creates the script with a draft that is not published. At most 50 live scripts per tenant (422 edge_script_limit); a name is unique per tenant (409 edge_script_name_conflict). Omitted settings take the defaults. Audit edge_script.create.
Request body
application/json · Required：Yes
createEdgeScript Request body| Name | Type | Required | Description |
|---|
failure_mode | string: deny / allow | No | deny answers 503 on an error or limit hit, allow lets the request through and drops the script's intents. |
|---|
max_instructions | integer | No | — |
|---|
max_time_ms | integer | No | — |
|---|
max_memory_kb | integer | No | — |
|---|
name | string | Yes | — |
|---|
description | string | No | — |
|---|
source | string | No | — |
|---|
Responses
createEdgeScript Responses| Status | Description |
|---|
201 | Created. Fields：failure_mode?: string: deny / allow max_instructions?: integer max_time_ms?: integer max_memory_kb?: integer id: string(uuid) name: string description: string source: string current_version: integer latest_version: integer dirty: boolean reference_count: integer revision: integer updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
422 | The request is well formed but breaks a business rule (error.code names it). |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/edge-scripts/check
Check an edge script source
- operationId
checkEdgeScript- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.read. Parses the source and checks forbidden identifiers, string.dump, concatenation chains over 16 operands and the 32 KiB size; never runs it. Not stored, not audited. Each diagnostic carries a 1-based line (0: the whole source).
Request body
application/json · Required：Yes
checkEdgeScript Request body| Name | Type | Required | Description |
|---|
source | string | Yes | — |
|---|
Responses
checkEdgeScript Responses| Status | Description |
|---|
200 | The check result. Fields：ok: boolean diagnostics: array<object> |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/edge-scripts/trial
Run an edge script against a sample request
- operationId
trialEdgeScript- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.read. Runs the source in a resource-limited child process of the control plane: a simulation, not the node's result (instruction counts are not reported, bit and country are simulated; the node's real result is in the security log). 500 ms wall clock; at most 4 trials at once; 30 trials per tenant per minute (429 edge_script_trial_rate_limited). A source that fails the check answers outcome fail, reason syntax. Not stored, not audited.
Request body
application/json · Required：Yes
trialEdgeScript Request body| Name | Type | Required | Description |
|---|
source | string | Yes | — |
|---|
failure_mode | string: deny / allow | No | — |
|---|
request | object | No | — |
|---|
Responses
trialEdgeScript Responses| Status | Description |
|---|
200 | The trial result. Fields：outcome: string: continue / exit / fail reason?: string detail?: string status?: integer redirect?: string response_headers: array<EdgeScriptTrialHeader> request_headers: array<EdgeScriptTrialHeader> elapsed_ms: number failure_mode: string |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
429 | Too many trials (edge_script_trial_rate_limited). |
|---|
503 | Trials are not configured (edge_scripts_unavailable). |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.429 Rate limited: wait, then retry with lower concurrency.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/edge-scripts/{script_id}
Get an edge script
- operationId
getEdgeScript- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.read. The script with its draft; dirty is true when the draft differs from the current version.
Parameters
getEdgeScript Parameters| Name | In | Type | Required | Description |
|---|
script_id | path | string(uuid) | Yes | — |
|---|
Responses
getEdgeScript Responses| Status | Description |
|---|
200 | The script. Fields：failure_mode?: string: deny / allow max_instructions?: integer max_time_ms?: integer max_memory_kb?: integer id: string(uuid) name: string description: string source: string current_version: integer latest_version: integer dirty: boolean reference_count: integer revision: integer updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.
↑ Back to list
PUT /v1/edge-scripts/{script_id}
Save an edge script draft
- operationId
updateEdgeScript- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.manage, the current revision, module.edge_script and limits.edge_script. Replaces the name, description, settings and source of the draft (revision + 1); the nodes keep running the current version. Audit edge_script.update.
Parameters
updateEdgeScript Parameters| Name | In | Type | Required | Description |
|---|
script_id | path | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
updateEdgeScript Request body| Name | Type | Required | Description |
|---|
failure_mode | string: deny / allow | No | deny answers 503 on an error or limit hit, allow lets the request through and drops the script's intents. |
|---|
max_instructions | integer | No | — |
|---|
max_time_ms | integer | No | — |
|---|
max_memory_kb | integer | No | — |
|---|
name | string | Yes | — |
|---|
description | string | No | — |
|---|
source | string | No | — |
|---|
expected_revision | integer | Yes | — |
|---|
Responses
updateEdgeScript Responses| Status | Description |
|---|
200 | Saved. Fields：failure_mode?: string: deny / allow max_instructions?: integer max_time_ms?: integer max_memory_kb?: integer id: string(uuid) name: string description: string source: string current_version: integer latest_version: integer dirty: boolean reference_count: integer revision: integer updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
DELETE /v1/edge-scripts/{script_id}
Delete an edge script
- operationId
deleteEdgeScript- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.manage and the current revision (entitlement is not asked). A script a live policy runs is refused (409 edge_script_in_use). Audit edge_script.delete.
Parameters
deleteEdgeScript Parameters| Name | In | Type | Required | Description |
|---|
script_id | path | string(uuid) | Yes | — |
|---|
expected_revision | query | integer | Yes | — |
|---|
Responses
deleteEdgeScript Responses| Status | Description |
|---|
204 | Deleted. |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
POST /v1/edge-scripts/{script_id}/publish
Publish the draft of an edge script
- operationId
publishEdgeScript- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.manage, the current revision, module.edge_script and limits.edge_script. Checks the draft (422 edge_script_check_failed with diagnostics and line numbers), stores it as an immutable version latest + 1, makes it current and republishes every tenant whose bound WAF policy runs the script (system trigger edge_script). The newest 100 versions are kept. Audit edge_script.publish.
Parameters
publishEdgeScript Parameters| Name | In | Type | Required | Description |
|---|
script_id | path | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
publishEdgeScript Request body| Name | Type | Required | Description |
|---|
expected_revision | integer | Yes | — |
|---|
note | string | No | — |
|---|
Responses
publishEdgeScript Responses| Status | Description |
|---|
200 | Published. Fields：failure_mode?: string: deny / allow max_instructions?: integer max_time_ms?: integer max_memory_kb?: integer id: string(uuid) name: string description: string source: string current_version: integer latest_version: integer dirty: boolean reference_count: integer revision: integer updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
422 | The request is well formed but breaks a business rule (error.code names it). |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
GET /v1/edge-scripts/{script_id}/references
List the policies running an edge script
- operationId
listEdgeScriptReferences- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.read. The tenant's live WAF policies with a script rule naming it, by policy name; rule_count counts those rules.
Parameters
listEdgeScriptReferences Parameters| Name | In | Type | Required | Description |
|---|
script_id | path | string(uuid) | Yes | — |
|---|
Responses
listEdgeScriptReferences Responses| Status | Description |
|---|
200 | References. Fields：items: array<object> |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.
↑ Back to list
POST /v1/edge-scripts/{script_id}/rollback
Roll an edge script back to a version
- operationId
rollbackEdgeScript- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.manage, the current revision, module.edge_script and limits.edge_script. Makes an existing version current again (404 edge_script_version_not_found); the draft stays. Republishes every tenant running the script (system trigger edge_script). Audit edge_script.rollback.
Parameters
rollbackEdgeScript Parameters| Name | In | Type | Required | Description |
|---|
script_id | path | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
rollbackEdgeScript Request body| Name | Type | Required | Description |
|---|
expected_revision | integer | Yes | — |
|---|
version | integer | Yes | — |
|---|
Responses
rollbackEdgeScript Responses| Status | Description |
|---|
200 | Rolled back. Fields：failure_mode?: string: deny / allow max_instructions?: integer max_time_ms?: integer max_memory_kb?: integer id: string(uuid) name: string description: string source: string current_version: integer latest_version: integer dirty: boolean reference_count: integer revision: integer updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
GET /v1/edge-scripts/{script_id}/versions
List the versions of an edge script
- operationId
listEdgeScriptVersions- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.read. The kept versions, newest first, without sources.
Parameters
listEdgeScriptVersions Parameters| Name | In | Type | Required | Description |
|---|
script_id | path | string(uuid) | Yes | — |
|---|
Responses
listEdgeScriptVersions Responses| Status | Description |
|---|
200 | Versions. Fields：items: array<EdgeScriptVersion> |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.
↑ Back to list
GET /v1/edge-scripts/{script_id}/versions/{version}
Get one version of an edge script
- operationId
getEdgeScriptVersion- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires security_policies.read. The version with its source (the console loads it into the draft).
Parameters
getEdgeScriptVersion Parameters| Name | In | Type | Required | Description |
|---|
script_id | path | string(uuid) | Yes | — |
|---|
version | path | integer | Yes | — |
|---|
Responses
getEdgeScriptVersion Responses| Status | Description |
|---|
200 | The version. Fields：failure_mode?: string: deny / allow max_instructions?: integer max_time_ms?: integer max_memory_kb?: integer version: integer sha256: string note: string current: boolean published_at: string(date-time) source?: string |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.
↑ Back to list