Skip to main content

Delivery

Use Delivery to manage cache policies, image transforms and reusable error documents.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Cache policy overview​

Cache policy overview

Inspect a reusable cache policy and its request and response rules.

  1. Open Delivery, then Cache policies, and select a policy.
  2. Use Sample request to inspect the policy preview.
  3. Select Edit rules, Request Rules or Response Rules to manage the matching stage. Verify attachment in application or route settings.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/cache-policies" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.meta.total, data.meta.offset, data.meta.limit, data.meta.suggestedFilters. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: List cache policies associated with your account.

Cache policy overview (alternate view 2)​

Cache policy overview

Inspect a reusable cache policy and its request and response rules.

  1. Open Delivery, then Cache policies, and select a policy.
  2. Use Sample request to inspect the policy preview.
  3. Select Edit rules, Request Rules or Response Rules to manage the matching stage. Verify attachment in application or route settings.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $CACHE_POLICY_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/cache-policies/$CACHE_POLICY_ID" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.cachePolicyId, data.name, data.description, data.version. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: Get cache policy.

Cache request rules​

Cache request rules

Manage rules applied to requests before a cache lookup.

  1. Open a cache policy and select Request Rules, then Add request rule.
  2. Set the filter expression and cache behavior, then submit.
  3. Verify the rule and Status in the list.
FieldRequiredDescriptionMatching API field
Name (optional)NoUp to 64 characters.name
Filter expressionYesNon-empty matching expression.filterExpression
EnabledNoNew rules are enabled unless disabled.isDisabled
Edge TTL modeNoChoose origin-respecting behavior or override.edgeTtlMode
Edge TTL (seconds)For an edge TTL overrideNon-negative whole seconds.edgeTtlSeconds
Browser TTL modeNoChoose bypass, respect origin or override.browserTtlMode
Browser TTL (seconds)For a browser TTL overrideNon-negative whole seconds.browserTtlSeconds
Append (end) / Before rule / After ruleNoPlacement is converted into a priority, 1-100000000.priority
Bypass cacheYesMark a matching request as bypass or eligible.doBypassCache

API equivalent​

Add a request rule that bypasses the cache for example.com. Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $CACHE_POLICY_ID to the selected resources.

curl --fail-with-body --silent --show-error --request POST \
--url "https://<your-api-host>/cache-policies/$CACHE_POLICY_ID/request-rules" \
--header "x-api-key: $BALANCER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"priority":1000,"filterExpression":"http.host eq \"example.com\"","doBypassCache":true}'

Expect HTTP 200 with code set to 200. The response acknowledges the stored change. Reopen the portal screen or run the read example below to verify it.

API reference: Create an ordered request rule for a cache policy.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $CACHE_POLICY_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/cache-policies/$CACHE_POLICY_ID/request-rules" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.meta.total, data.meta.offset, data.meta.limit, data.meta.suggestedFilters. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: Returns the ordered list of request rules for a cache policy.

Cache response rules​

Cache response rules

Manage rules applied when deciding how to store an origin response.

  1. Open a cache policy and select Response Rules, then Add response rule.
  2. Set the filter expression and storage or TTL behavior, then submit.
  3. Verify the rule and Status in the list.
FieldRequiredDescriptionMatching API field
Name (optional)NoUp to 64 characters.name
Filter expressionYesNon-empty matching expression.filterExpression
EnabledNoNew rules are enabled unless disabled.isDisabled
Edge TTL modeNoChoose origin-respecting behavior or override.edgeTtlMode
Edge TTL (seconds)For an edge TTL overrideNon-negative whole seconds.edgeTtlSeconds
Browser TTL modeNoChoose bypass, respect origin or override.browserTtlMode
Browser TTL (seconds)For a browser TTL overrideNon-negative whole seconds.browserTtlSeconds
Append (end) / Before rule / After ruleNoPlacement is converted into a priority, 1-100000000.priority
Do not store (prevent edge caching)NoDo not store the response.doNotStore
Strip Set-CookieNoRemove the response header.stripSetCookie
Strip ETagNoRemove the response header.stripEtag
Strip Last-ModifiedNoRemove the response header.stripLastModified
Stale-while-revalidate (seconds)NoNon-negative whole seconds.staleWhileRevalidateSeconds
Keep seconds (for validator-based revalidation)NoNon-negative whole seconds.keepSeconds
DirectiveFor a directive actionSelect cache-control directive.cacheControlDirectiveActions.directive
OperationFor a directive actionSelect the action on the directive.cacheControlDirectiveActions.operation
ScopeFor a directive actionSelect scope.cacheControlDirectiveActions.scope

API equivalent​

Add a response rule that prevents storage for example.com. Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $CACHE_POLICY_ID to the selected resources.

curl --fail-with-body --silent --show-error --request POST \
--url "https://<your-api-host>/cache-policies/$CACHE_POLICY_ID/response-rules" \
--header "x-api-key: $BALANCER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"priority":1000,"filterExpression":"http.host eq \"example.com\"","doNotStore":true}'

Expect HTTP 200 with code set to 200. The response acknowledges the stored change. Reopen the portal screen or run the read example below to verify it.

API reference: Create an ordered response rule for a cache policy.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $CACHE_POLICY_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/cache-policies/$CACHE_POLICY_ID/response-rules" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.meta.total, data.meta.offset, data.meta.limit, data.meta.suggestedFilters. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: Returns the ordered list of response rules for a cache policy.

Cache policy settings​

Cache policy settings

Rename a cache policy or update its description.

  1. Open the cache policy and select Settings.
  2. Edit Name and Description (optional), then select Save.
  3. Reload Settings and verify the values. Select Cancel to discard unsaved changes.
FieldRequiredDescriptionMatching API field
NameYes1-64 characters.name
Description (optional)NoUp to 255 characters.description

API equivalent​

Update cache policy metadata. Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $CACHE_POLICY_ID to the selected resources.

curl --fail-with-body --silent --show-error --request PATCH \
--url "https://<your-api-host>/cache-policies/$CACHE_POLICY_ID" \
--header "x-api-key: $BALANCER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"description":"Static content for example.com"}'

Expect HTTP 200 with code set to 200. The response acknowledges the stored change. Reopen the portal screen or run the read example below to verify it.

API reference: Update a cache policy.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $CACHE_POLICY_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/cache-policies/$CACHE_POLICY_ID" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.cachePolicyId, data.name, data.description, data.version. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: Get cache policy.

Image policy overview​

Image policy overview

Inspect image policy variants, transforms and usage.

  1. Open Delivery, then Image manipulation, and select a policy.
  2. Select Edit variants for named transforms or Edit for policy settings.
  3. Verify the variant names and canonical transform strings before using them in request URLs.
FieldRequiredDescriptionMatching API field
NameYes, when creating a policy1-64 characters.name

API equivalent​

Create an image policy before configuring transforms and variants. Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context.

curl --fail-with-body --silent --show-error --request POST \
--url "https://<your-api-host>/image-manipulation-policies" \
--header "x-api-key: $BALANCER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"example.com"}'

Expect HTTP 200 with code set to 200. The response acknowledges the stored change. Reopen the portal screen or run the read example below to verify it.

API reference: Create a new reusable image manipulation policy.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/image-manipulation-policies" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.meta.total, data.meta.offset, data.meta.limit, data.meta.suggestedFilters. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: List image manipulation policies.

Image policy overview (alternate view 2)​

Image policy overview

Inspect image policy variants, transforms and usage.

  1. Open Delivery, then Image manipulation, and select a policy.
  2. Select Edit variants for named transforms or Edit for policy settings.
  3. Verify the variant names and canonical transform strings before using them in request URLs.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $IMAGE_MANIPULATION_POLICY_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/image-manipulation-policies/$IMAGE_MANIPULATION_POLICY_ID" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.name, data.version, data.ops.width.enabled, data.ops.height.enabled. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: Get one image manipulation policy.

Image policy settings​

Image policy settings

Set allowed image transforms, formats and input limits.

  1. Open an image policy and select Settings.
  2. Review the defaults, quality bounds, format options and maximum input dimensions.
  3. Select Save, reload and verify the settings.
FieldRequiredDescriptionMatching API field
NameYes when supplied1-64 characters.name
Default fit modeNocover, contain, fill or scale-down.ops.fit.default
Maximum DPRNoMaximum device pixel ratio.ops.dpr.max
Default output formatNoauto, webp, avif, heif, jpeg, png, gif or jxl.ops.format.default
Default metadata handlingNostrip or keep.ops.metadata.default
Min qualityNo1-100 on the displayed control.ops.quality.min
Max qualityNo1-100 on the displayed control.ops.quality.max
Default gravityNoCrop anchor.ops.gravity.default
Default rotationNoRotation value.ops.rotate.default
Max blur sigmaNoMaximum allowed blur.ops.blur.maxSigma
Max sharpen sigmaNoMaximum allowed sharpening.ops.sharpen.maxSigma
Max Width (px)No1-8192 pixels.bounds.maxWidth
Max Height (px)No1-8192 pixels.bounds.maxHeight
Max PixelsNo1-100000000 pixels.bounds.maxPixels
Max Input File Size (bytes)No1-67108864 bytes.bounds.maxInputBytes
WidthNoAllow this operation when enabled.ops.width.enabled
HeightNoAllow this operation when enabled.ops.height.enabled
FitNoAllow this operation when enabled.ops.fit.enabled
DprNoAllow this operation when enabled.ops.dpr.enabled
FormatNoAllow this operation when enabled.ops.format.enabled
MetadataNoAllow this operation when enabled.ops.metadata.enabled
QualityNoAllow this operation when enabled.ops.quality.enabled
GravityNoAllow this operation when enabled.ops.gravity.enabled
FocalNoAllow this operation when enabled.ops.focal.enabled
RotateNoAllow this operation when enabled.ops.rotate.enabled
FlipNoAllow this operation when enabled.ops.flip.enabled
PadNoAllow this operation when enabled.ops.pad.enabled
BlurNoAllow this operation when enabled.ops.blur.enabled
SharpenNoAllow this operation when enabled.ops.sharpen.enabled
TrimNoAllow this operation when enabled.ops.trim.enabled
WEBPNoEnable this output format.outputFormats.webp.enabled
AVIFNoEnable this output format.outputFormats.avif.enabled
HEIFNoEnable this output format.outputFormats.heif.enabled
JPEGNoEnable this output format.outputFormats.jpeg.enabled
PNGNoEnable this output format.outputFormats.png.enabled
JXLNoEnable this output format.outputFormats.jxl.enabled
GIFNoEnable this output format.outputFormats.gif.enabled
JPEG (quality)NoPer-codec quality default, 1-100 on the displayed control.ops.quality.defaults.jpeg
WEBP (quality)NoPer-codec quality default, 1-100 on the displayed control.ops.quality.defaults.webp
AVIF (quality)NoPer-codec quality default, 1-100 on the displayed control.ops.quality.defaults.avif
JXL (quality)NoPer-codec quality default, 1-100 on the displayed control.ops.quality.defaults.jxl

API equivalent​

Set the maximum output dimensions on the selected policy. Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $IMAGE_MANIPULATION_POLICY_ID to the selected resources.

curl --fail-with-body --silent --show-error --request PATCH \
--url "https://<your-api-host>/image-manipulation-policies/$IMAGE_MANIPULATION_POLICY_ID" \
--header "x-api-key: $BALANCER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"bounds":{"maxWidth":1920,"maxHeight":1080}}'

Expect HTTP 200 with code set to 200. The response acknowledges the stored change. Reopen the portal screen or run the read example below to verify it.

API reference: Update an image manipulation policy.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $IMAGE_MANIPULATION_POLICY_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/image-manipulation-policies/$IMAGE_MANIPULATION_POLICY_ID" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.name, data.version, data.ops.width.enabled, data.ops.height.enabled. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: Get one image manipulation policy.

Image variants​

Image variants

Manage named transform strings within an image policy.

  1. Open the image policy and select Variants, then Add Variant.
  2. Enter Name and Ops String, then submit.
  3. Verify the variant in the list and use its name when requesting that transform.
FieldRequiredDescriptionMatching API field
NameYes1-64 characters.name
Ops StringNoUp to 256 characters; empty transform strings are accepted by this form.canonicalOpsString

API equivalent​

Add a named width transform. Enable the Width operation in the policy before using the variant. Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $IMAGE_MANIPULATION_POLICY_ID to the selected resources.

curl --fail-with-body --silent --show-error --request POST \
--url "https://<your-api-host>/image-manipulation-policies/$IMAGE_MANIPULATION_POLICY_ID/variants" \
--header "x-api-key: $BALANCER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"thumbnail","canonicalOpsString":"w=320"}'

Expect HTTP 200 with code set to 200. The response acknowledges the stored change. Reopen the portal screen or run the read example below to verify it.

API reference: Create a new named image manipulation variant inside one policy.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $IMAGE_MANIPULATION_POLICY_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/image-manipulation-policies/$IMAGE_MANIPULATION_POLICY_ID/variants" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.meta.total, data.meta.offset, data.meta.limit, data.meta.suggestedFilters. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: List variants for one image manipulation policy.

Error pages​

Error pages

Manage reusable error documents and inspect where they are bound.

  1. Open Delivery, then Error pages. Select New error page.
  2. Enter Name, Content Type and HTML Body, then save.
  3. Select Edit document to change a document, or Check where these are used to review bindings. Verify the saved preview.
FieldRequiredDescriptionMatching API field
NameYes1-64 characters.name
Description (optional)NoUp to 255 characters.description
Content TypeNoResponse content type.contentType
HTML BodyYesNon-empty document. Validation: Body is required.body

API equivalent​

Create a reusable error document. Bind it through an application or route error page rule. Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context.

curl --fail-with-body --silent --show-error --request POST \
--url "https://<your-api-host>/error-page-assets" \
--header "x-api-key: $BALANCER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"example.com","contentType":"text/html","body":"<p>Please try again later.</p>"}'

Expect HTTP 200 with code set to 200. The response acknowledges the stored change. Reopen the portal screen or run the read example below to verify it.

API reference: Create a new reusable custom error page asset.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/error-page-assets" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.meta.total, data.meta.offset, data.meta.limit, data.meta.suggestedFilters. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: List custom error page assets.

Error pages (alternate view 2)​

Error pages

Manage reusable error documents and inspect where they are bound.

  1. Open Delivery, then Error pages. Select New error page.
  2. Enter Name, Content Type and HTML Body, then save.
  3. Select Edit document to change a document, or Check where these are used to review bindings. Verify the saved preview.
FieldRequiredDescriptionMatching API field
NameYes1-64 characters.name
Description (optional)NoUp to 255 characters.description
Content TypeNoResponse content type.contentType
HTML BodyYesNon-empty document. Validation: Body is required.body

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/error-page-assets" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.meta.total, data.meta.offset, data.meta.limit, data.meta.suggestedFilters. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: List custom error page assets.

Error page usage​

Error page usage

Review the application and route rules that reference an error document.

  1. Open an error page usage view.
  2. Review its bindings before editing or deleting the document. Select Preview to inspect the content or Settings to edit it.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $ERROR_PAGE_ASSET_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/error-page-assets/$ERROR_PAGE_ASSET_ID" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.errorPageAssetId, data.name, data.description, data.contentType. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: Get custom error page asset.

Error page preview​

Error page preview

Inspect a document as rendered content or source text.

  1. Open an error document and select Preview.
  2. Switch between Rendered and Raw HTML. Verify that the intended content is present.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $ERROR_PAGE_ASSET_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/error-page-assets/$ERROR_PAGE_ASSET_ID" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.errorPageAssetId, data.name, data.description, data.contentType. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: Get custom error page asset.

Error page settings​

Error page settings

Edit the reusable document served by error page bindings.

  1. Open the document and select Settings.
  2. Edit Name, Description (optional), Content Type or HTML Body. Select Save changes.
  3. Open Preview and verify the saved content.
FieldRequiredDescriptionMatching API field
NameYes1-64 characters.name
Description (optional)NoUp to 255 characters.description
Content TypeNoResponse content type.contentType
HTML BodyYesNon-empty document. Validation: Body is required.body

API equivalent​

Update the selected error document. Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $ERROR_PAGE_ASSET_ID to the selected resources.

curl --fail-with-body --silent --show-error --request PATCH \
--url "https://<your-api-host>/error-page-assets/$ERROR_PAGE_ASSET_ID" \
--header "x-api-key: $BALANCER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"body":"<p>Please try again later.</p>"}'

Expect HTTP 200 with code set to 200. The response acknowledges the stored change. Reopen the portal screen or run the read example below to verify it.

API reference: Update a custom error page asset.

Verify with the API​

Use the API host shown in the Balancer portal in place of https://<your-api-host>. Set $BALANCER_API_KEY to your credential for this context. Set $ERROR_PAGE_ASSET_ID to the resource identifiers you want to inspect.

curl --fail-with-body --silent --show-error --request GET \
--url "https://<your-api-host>/error-page-assets/$ERROR_PAGE_ASSET_ID" \
--header "x-api-key: $BALANCER_API_KEY"

Expect HTTP 200 with code set to 200. The response includes data.errorPageAssetId, data.name, data.description, data.contentType. Compare the returned configuration with the screen. A successful configuration read does not verify that an edge has applied it.

API reference: Get custom error page asset.