--- name: azion-create-a-cache-setting description: >- Create a cache setting on an application and apply it with a rule, from Azion Console, the Azion API, or the Azion CLI. --- # Create a cache setting You create a cache setting on an application from Azion Console, the Azion API v4, or the Azion CLI, and apply it to requests with a [Rules Engine](/en/documentation/platform/applications/rules-engine/) rule. A setting holds the TTLs and the variation rules; until a rule names it through the **Set Cache Policy** behavior, it applies to no request. For a first cache setting through the Console alone, refer to the [Cache quickstart](/en/documentation/platform/applications/cache/quickstart/). To vary the cache by a query string argument or a cookie, refer to [Configure Advanced Cache Key for an application](/en/documentation/guides/application-performance/cache-and-purge/advanced-cache-key/). --- ## Prerequisites - An application. To create one, refer to [Applications quickstart](/en/documentation/platform/applications/quickstart/). - Access to Azion Console, for the Console procedures. Refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/), for the API procedures. - The [Azion CLI](/en/documentation/devtools/cli/) installed and authorized, for the CLI procedures. - [Application Accelerator](/en/documentation/platform/applications/#application-accelerator) on the application, for a **Max Age** below 60 seconds or for cache variation. --- ## Create the cache setting through Azion Console The **Create Cache Settings** drawer carries every field of a setting. To create one: 1. **Open the application** Access [Azion Console](https://console.azion.com/) > **Applications**, then select the application. 2. **Go to the Cache Settings tab** 3. **Select + Cache** 4. **Name the cache setting** In **Name**, enter a unique, descriptive name. 5. **Choose the browser cache behavior** Under **Browser Cache**, select one option. *Honor cache policies* forwards the origin's `Cache-Control` and `Expires` headers to the browser. *Override cache settings* replaces them with a TTL you enter. *No cache* disables browser caching, so content is always fetched from the server. 6. **Choose the cache behavior** Under **Cache**, select *Honor cache policies* to keep the origin's headers, or *Override cache behavior* to replace them. 7. **Set Max Age** In **Max Age**, enter the seconds Azion keeps a copy. A new setting carries `60`. 8. **Turn on Stale cache** With the toggle on, Azion serves an expired copy when a revalidation attempt with the origin fails. 9. **Turn on Large file optimization** With the toggle on, Azion caches a large object in fragments rather than as one piece. 10. **Turn on Tiered Cache** The toggle adds a second cache layer between Azion's cache and the origin. It requires *Override cache behavior* and a **Max Age** of at least 3 seconds. 11. **Select Save** The setting appears in the **Cache Settings** list with its **Name**, **ID**, **Browser Cache**, and **Cache**. For every field with its type, its default, and its bounds, refer to [Cache settings](/en/documentation/platform/applications/cache/cache-settings/). --- ## Apply the setting with a rule A rule in the request phase decides which requests the setting covers. To create it: 1. **Go to the Rules Engine tab** 2. **Select + Rule** 3. **Name the rule** 4. **Select Request Phase** 5. **Set the criteria** Under **Criteria**, select `${uri}`, an operator, and the argument that matches the paths to cache. 6. **Add the Set Cache Policy behavior** Under **Behaviors**, select **Set Cache Policy**, then select the cache setting. 7. **Select Save** The rule appears in the list and applies the setting to every request its criteria match. > **Note** > > A new rule can take a few minutes to propagate. Wait before you check the cache status of a response. --- ## Create the cache setting through the API Two requests create the setting and the rule that applies it. To send them: 1. **Create the cache setting** ```bash curl --location --request POST 'https://api.azion.com/v4/workspace/applications/{application_id}/cache_settings' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{ "name": "static-assets", "browser_cache": { "behavior": "no-cache" }, "modules": { "cache": { "behavior": "override", "max_age": 300, "stale_cache": { "enabled": true }, "large_file_cache": { "enabled": true, "offset": 1024 }, "tiered_cache": { "enabled": true, "topology": "nearest-region" } } } }' ``` 2. **Read the id in the response** The API answers with HTTP `201`, `state` set to `executed`, and the new setting under `data`: ```json {"state":"executed","data":{"id":123456,"name":"static-assets","browser_cache":{"behavior":"no-cache","max_age":0},"modules":{"cache":{"behavior":"override","max_age":300,"stale_cache":{"enabled":true},"large_file_cache":{"enabled":true,"offset":1024},"tiered_cache":{"topology":"nearest-region","enabled":true}}},"created_at":"2026-01-01T12:00:00.577248Z"}} ``` 3. **Create the rule that applies it** Replace `[CACHE SETTING ID]` with the `id` the response returned: ```bash curl --location --request POST 'https://api.azion.com/v4/workspace/applications/{application_id}/request_rules' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{ "name": "apply-static-assets-cache", "criteria": [[{ "variable": "${uri}", "operator": "starts_with", "conditional": "if", "argument": "/static/" }]], "behaviors": [{ "type": "set_cache_policy", "attributes": { "value": "[CACHE SETTING ID]" } }] }' ``` 4. **Read the rule response** The API answers with HTTP `202` and the rule with `state` set to `pending`, because a new rule propagates before it applies: ```json {"state":"pending","data":{"id":234572,"name":"apply-static-assets-cache","active":true,"order":0}} ``` The setting now applies to every request whose path starts with the argument. To list the settings of an application, send `GET` to the same `cache_settings` path. --- ## Create the cache setting through the Azion CLI The CLI covers part of the object with flags, and the whole of it with a JSON file. To create a setting from flags: 1. **Run the create command** ```bash azion create cache-setting \ --application-id \ --name "product-listing" \ --browser-cache-behavior override \ --browser-cache-max-age 30 \ --cache-by-query-string allowlist \ --query-string-fields "category,page" \ --cache-by-cookies allowlist \ --cookie-names "session_id" ``` 2. **Read the id in the output** ```text Created Cache Settings configuration with ID 123457 ``` 3. **Read the setting back** ```bash azion describe cache-setting --application-id --cache-setting-id 123457 --format json ``` The object carries the browser cache and the variation fields the flags set, and `modules.cache` at its defaults: `honor` and `60`. To create a setting with the fields the flags do not cover, send the request body from a file: 1. **Write the body to a file** Save the API request body above as `cache-setting.json`. 2. **Create the setting from the file** ```bash azion create cache-setting --application-id --file cache-setting.json ``` The command prints the id of the new setting: ```text Created Cache Settings configuration with ID 123458 ``` > **Note** > > The CLI flags do not set **Max Age**, the cache behavior, stale cache, Large File Optimization, or Tiered Cache. Use `--file` with the request body for those fields. The CLI does not create the rule that applies the setting. Create it through the Console or the API, with either procedure on this page. For every flag, refer to [Azion CLI create](/en/documentation/devtools/cli/resources/). --- ## Next steps - [Cache settings](/en/documentation/platform/applications/cache/cache-settings.md): Every field of a cache setting, with its type, its default per interface, and its bounds. - [Expiration and freshness](/en/documentation/platform/applications/cache/expiration-and-freshness.md): What the TTL, stale cache, and the second layer do to a request. - [Configure cache policies for an application](/en/documentation/guides/application-performance/cache-and-purge/cache-settings.md): Set a TTL for one path, bypass the cache for another, and forward cookies. - [Purge cached content](/en/documentation/guides/application-performance/cache-and-purge/purge-cached-content.md): Remove a stored copy before the TTL of this setting ends. - [Accelerate websites and APIs with a CDN](/en/documentation/use-cases/improve-performance-and-reliability/accelerate-websites-and-apis-with-a-cdn.md): Two cache settings, one with Tiered Cache, that serve a site's static files and pages near its users.