API Configuration Reference

This page documents the JSON format used when reading or writing configuration via the wizard API (/wizard/core endpoints). Every field that appears in the UI wizard corresponds to a key in this format except for domains and origins which are managed on their own endpoints.

Duration strings

Fields marked as duration accept duration strings, composed of a number and a unit suffix:

Examples: "10s", "5m".

Top-level structure

{
  "general": { },
  "highAvailability": { },
  "queryParams": { },
  "headers": { },
  "cookies": { },
  "security": { },
  "optimisation": { },
  "overrides": [ ]
}

highAvailability and optimisation are optional — they are omitted entirely when the corresponding features are disabled.

general

highAvailability

This key is optional — it is omitted entirely when no high-availability features are enabled.

queryParams

Action values:

• "off" — Query parameters are passed through unchanged with no processing.
• "redirect" — Strip all query parameters and redirect the client to the cleaned URL.
• "continue" — Strip all query parameters and continue serving from the cleaned URL without redirecting.
• "sort" — Sort query parameters alphabetically to improve cache hit rates.

headers

cookies

cookies.onCookie

Controls how incoming request cookies are handled. Exactly one of action or allowList is present — they are mutually exclusive.

cookies.onSetCookie

Controls how Set-Cookie response headers from the origin are handled. Exactly one of action, allowList, or denyList is present.

security

optimisation

This key is optional — it is omitted entirely when WebP image optimisation is disabled.

overrides

An array of rules that override specific settings for requests matching a given path or file extension. Each rule in the array is an object with the following fields:

Exactly one of paths or extensions must be non-empty — they are mutually exclusive. A rule matches by path or by extension, not both.

Override rule entries

Each entry in the rules array overrides one wizard field for requests that match the override:

The value type must match the field type:

• Boolean fields: true or false
• String/select fields: a string, e.g. "remove" or "deny"
• Array fields: a JSON array of strings, e.g. ["session", "cart"]
• Table fields (setBackendHeaders, setHeadersForDelivery): an array of {"name": "...", "value": "..."} objects

Matching and precedence

• Overrides are evaluated in the order they appear in the array.
• If a request matches multiple overrides, only the first matching override is applied.
• paths and extensions are mutually exclusive. Only one should be non-empty per rule.
• Paths support a leading ^ regex character so that a path of /api/ will match /v1/api/endpoint but ^/api/ would not.

Example

{
  "overrides": [
    {
      "name": "Cache static assets for 30 days",
      "paths": [],
      "extensions": ["jpg", "png", "webp", "css", "js"],
      "rules": [
        { "stringId": "general.uncacheable", "value": false },
        { "stringId": "general.cacheableTTLOverride", "value": "30d" }
      ]
    },
    {
      "name": "API passthrough — no caching, no cookies stripped",
      "paths": ["/api/"],
      "extensions": [],
      "rules": [
        { "stringId": "general.uncacheable", "value": true },
        { "stringId": "cookies.onCookie.action", "value": "pass" }
      ]
    },
    {
      "name": "Admin area — allow list only",
      "paths": ["/admin/"],
      "extensions": [],
      "rules": [
        { "stringId": "security.allowList.enable", "value": true },
        { "stringId": "security.allowList.acl", "value": ["10.0.0.0/8", "192.168.1.0/24"] }
      ]
    }
  ]
}