Overview

When you create a workspace with the Fresca product ID, Delivery Manager seeds every new environment version with a pre-populated group of settings. These settings are the foundational layer of your configuration: they sit at the top of the default rule set and apply to every incoming request unless a rule lower in the tree overrides them.

The values aren't arbitrary. They're tuned for Ion's delivery profile, including high origin offload, low time to first byte, and a security posture that doesn't leak origin detail, so in most cases your job through the API is to fill in the handful of account-specific values the template can't know, such as origin hostname, and leave the rest unchanged.

This page explains the JSON syntax of that template, what each setting does, why it ships with the value it does, and which values you must change before your first activation. It's the API counterpart of Settings > Ion.

📘

Ion is Fresca

Fresca is the product ID for Ion in the Delivery Manager API. List products returns it for every contract that's entitled to Ion.

Where the defaults come from

Two operations matter:

Read the template before you write your first environment version. It's the only place the shipped values are expressed in full, and it's versioned: catalogVersion and latestRuleFormat in the same response tell you which catalog produced them.

🚧

Two different "defaults" exist

behaviorDefinitions[<behavior>].options[*].defaultVal is the behavior schema default: the value a behavior falls back to anywhere in a rule tree. newEnvironmentVersionTemplate is the Ion product template: what your environment version is actually created with. The product template deliberately overrides the schema default in more than a dozen places — caching option, DNS refresh timeout, cache key handling, redirect status code, failover action, and others. When this page says "ships as," it means the product template. Reference pages under Behaviors describe the schema, not the Ion template.

Settings categories

settingsCategories in the product definition groups the settings for display. The grouping is presentational and it doesn't affect evaluation. It's what the Delivery Manager's application category pages are named after, so it's the quickest way to map an API name to its UI documentation.

Syntax

The settings object

Default settings live in the defaultRuleSet.defaultSettings array of an environment version. Each entry is a behavior object with two members:

{
  "name": "dnsAsyncRefresh",
  "options": {
    "enabled": true,
    "timeout": "5h"
  }
}

• name — the setting's API name, camelCase. Refer to Settings categories and specific category subsections in this document for valid names.

  🚧

  Currently, Delivery Manager API silently ignores any invalid names. This validation fix is coming in the next releases.

• options — the behavior's options. Option availability is often conditional: an option only belongs in the object when its parent option has the right value. Each behavior's reference page states those dependencies in its Requires column, and this page marks the ones that affect the Ion defaults.

Array order carries no meaning. Two entries with the same name aren't allowed in defaultSettings.

Template behaviors

Some settings are wrapped intoTemplates — cachingTemplate, failoverTemplate, allowMethodsTemplate, and so on. These are composite behaviors: one object that stands in for what a Property Manager's Ion property expressed as several separate behaviors inside several pre-added child rules. cachingTemplate alone carries the caching policy, tiered distribution, ETag validation, cache key handling, error caching, prefreshing, and six per-content-type caching blocks.

Two consequences for API work:

• Template behaviors are valid only in defaultSettings. Templates don't work in rules[] or in a custom rule set. Use the equivalent individual behaviors there (for example, caching, cacheKeyQueryParams, tieredDistribution).
• Their options are flat, not nested. Every per-content-type field is a sibling key with a prefix: cacheImagesTtl, cacheImagesPolicy, cacheImagesExtensions. There are no sub-objects.

defaultSettingsEnabled

defaultRuleSet.defaultSettingsEnabled controls whether the product's optimized group of features
applies to the environment version at all:

{
  "defaultRuleSet": {
    "defaultSettingsEnabled": true,
    "defaultSettings": [ ... ],
    "rules": [ ... ]
  }
}

Keep it true unless you have a specific reason to build a configuration from bare behaviors. Setting it to false discards the best-practice baseline described on this page, and you then own every value in it, including the ones Ion's validation requires.

Change a default value

Use a read-modify-write cycle against the version itself:

1. GET /products/Fresca once, to see the shipped template and the catalog version it came from.
2. POST .../versions to create the version, or GET .../versions/{version} to read the one you
   have.
3. Modify the defaultSettings entries you care about.
4. PUT /workspaces/{workspaceName}/environments/{environmentName}/versions/{version} with the
   defaultSettings array in full.

Sending the complete array is the safe pattern: it's explicit about every value, it's diffable in source control, and it behaves identically whether you're creating or updating a version. Build it from the template response rather than hand-writing it, so a catalog update doesn't silently drop settings you never looked at.

You can edit a version until it's activated. After activation, create a new version.

📘

The UI writes to the same place

Changes made on the Settings tab are synchronized with the Default settings rule under the Default rule set, which is the defaultRuleSet.defaultSettings array this page describes. The UI and the API are two views of one object.

Fill in required values before activating

The template is complete except for values Akamai can't supply for you. These ones block activation
or prevent configuration from executing the intended business logic:

Validation

validationRules in the product definition states what Ion requires of any environment version. For Ion:

{
  "validation": {
    "required_features": {
      "default_rule": ["origin", "cpCode"],
      "any_rule": ["caching"]
    }
  }
}

• default_rule — your default settings must configure an origin and a CP code. The template satisfies both (setOriginTemplate, cpCode), so you only break this by removing them.
• any_rule — caching must be configured somewhere in the rule tree. cachingTemplate satisfies it in the default settings.

Validation runs on activation, not on POST or PUT, so an environment version can be saved and still be unactivatable. Run Get validation resources to see what your version needs before activating.

Overriding a default for some requests

Default settings apply to every request. To change behavior for a subset, don't edit the default settings — add a rule instead. Rule configuration evaluates top down and the bottom-most match wins, so a rule placed below the default settings overrides them for the requests it matches:

{
  "defaultRuleSet": {
    "defaultSettingsEnabled": true,
    "defaultSettings": [ ... ],
    "rules": [
      {
        "name": "Override caching",
        "description": "Disables caching for dynamic objects",
        "criteria": [
          {
            "name": "path",
            "options": {
              "values": ["/dynamic"]
            }
          }
        ],
        "behaviors": [
          {
            "name": "caching",
            "options": {
              "behavior": "NO_STORE"
            }
          }
        ],
        "tags": ["caching"]
      }
    ]
  }
}

Note that the rule uses the individual caching behavior, not cachingTemplate. Template behaviors belong only in defaultSettings.

For logic you want to share or version separately, use a custom ruleset and position it with
ruleSetOrder. See Rule configuration logic for precedence and nesting.

What's not in the default settings

The Ion catalog carries far more behaviors than the template covers. Everything else isavailable to you through standalone behaviors and match criteria, and you add them to a rule rather than to
defaultSettings.

Check behaviorDefinitions in the product definition for the full catalog and the behavior versions
your rule format supports.

Coming from an Ion property

If you're porting a PAPI configuration, a classic Ion property arrived as pre-added child rules under the Default Rule, each holding individual behaviors. Here, one flat defaultSettings array holds composite *Template behaviors instead. cachingTemplate replaces a rule's worth of caching behaviors; allowMethodsTemplate replaces seven allow* behaviors.