# Cache

## Purge Cached Content

`cache.purge(CachePurgeParams**kwargs)  -> CachePurgeResponse`

**post** `/zones/{zone_id}/purge_cache`

### Purge All Cached Content

Removes ALL files from Cloudflare's cache. All tiers can purge everything.

```
{"purge_everything": true}
```

### Purge Cached Content by URL

Granularly removes one or more files from Cloudflare's cache by specifying URLs. All tiers can purge by URL.

To purge files with custom cache keys, include the headers used to compute the cache key as in the example. If you have a device type or geo in your cache key, you will need to include the CF-Device-Type or CF-IPCountry headers. If you have lang in your cache key, you will need to include the Accept-Language header.

**NB:** When including the Origin header, be sure to include the **scheme** and **hostname**. The port number can be omitted if it is the default port (80 for http, 443 for https), but must be included otherwise.

Single file purge example with files:

```
{"files": ["http://www.example.com/css/styles.css", "http://www.example.com/js/index.js"]}
```

Single file purge example with url and header pairs:

```
{"files": [{"url": "http://www.example.com/cat_picture.jpg", "headers": {"CF-IPCountry": "US", "CF-Device-Type": "desktop", "Accept-Language": "zh-CN"}}, {"url": "http://www.example.com/dog_picture.jpg", "headers": {"CF-IPCountry": "EU", "CF-Device-Type": "mobile", "Accept-Language": "en-US"}}]}
```

### Purge Cached Content by Tag, Host or Prefix

Granularly removes one or more files from Cloudflare's cache either by specifying the host, the associated Cache-Tag, or a Prefix.

Flex purge with tags:

```
{"tags": ["a-cache-tag", "another-cache-tag"]}
```

Flex purge with hosts:

```
{"hosts": ["www.example.com", "images.example.com"]}
```

Flex purge with prefixes:

```
{"prefixes": ["www.example.com/foo", "images.example.com/bar/baz"]}
```

### Availability and limits

Please refer to [purge cache availability and limits documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/#availability-and-limits).

### Parameters

- `zone_id: str`

- `tags: Optional[Sequence[str]]`

  For more information on cache tags and purging by tags, please refer to [purge by cache-tags documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/).

### Returns

- `class CachePurgeResponse: …`

  - `id: str`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.purge(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(response.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353"
  }
}
```

## Purge Cached Content by Environment

`cache.purge_environment(strenvironment_id, CachePurgeEnvironmentParams**kwargs)  -> CachePurgeEnvironmentResponse`

**post** `/zones/{zone_id}/environments/{environment_id}/purge_cache`

Purge cached content scoped to a specific environment. Supports the same purge types as the zone-level endpoint (purge everything, by URL, by tag, host, or prefix).

### Availability and limits

Please refer to [purge cache availability and limits documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/#availability-and-limits).

### Parameters

- `zone_id: str`

- `environment_id: str`

- `tags: Optional[Sequence[str]]`

  For more information on cache tags and purging by tags, please refer to [purge by cache-tags documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/).

### Returns

- `class CachePurgeEnvironmentResponse: …`

  - `id: str`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.purge_environment(
    environment_id="023e105f4ecef8ad9ca31a8372d0c353",
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(response.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353"
  }
}
```

## Domain Types

### Cache Purge Response

- `class CachePurgeResponse: …`

  - `id: str`

### Cache Purge Environment Response

- `class CachePurgeEnvironmentResponse: …`

  - `id: str`

# Cache Reserve

## Get Cache Reserve setting

`cache.cache_reserve.get(CacheReserveGetParams**kwargs)  -> CacheReserveGetResponse`

**get** `/zones/{zone_id}/cache/cache_reserve`

Increase cache lifetimes by automatically storing all cacheable files into Cloudflare's persistent object storage buckets. Requires Cache Reserve subscription. Note: using Tiered Cache with Cache Reserve is highly recommended to reduce Reserve operations costs. See the [developer docs](https://developers.cloudflare.com/cache/about/cache-reserve) for more information.

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class CacheReserveGetResponse: …`

  - `id: CacheReserve`

    The identifier of the caching setting.

    - `"cache_reserve"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Cache Reserve zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
cache_reserve = client.cache.cache_reserve.get(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(cache_reserve.id)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "editable": true,
    "id": "cache_reserve",
    "value": "off"
  },
  "success": true
}
```

## Change Cache Reserve setting

`cache.cache_reserve.edit(CacheReserveEditParams**kwargs)  -> CacheReserveEditResponse`

**patch** `/zones/{zone_id}/cache/cache_reserve`

Increase cache lifetimes by automatically storing all cacheable files into Cloudflare's persistent object storage buckets. Requires Cache Reserve subscription. Note: using Tiered Cache with Cache Reserve is highly recommended to reduce Reserve operations costs. See the [developer docs](https://developers.cloudflare.com/cache/about/cache-reserve) for more information.

### Parameters

- `zone_id: str`

  Identifier.

- `value: Literal["on", "off"]`

  Value of the Cache Reserve zone setting.

  - `"on"`

  - `"off"`

### Returns

- `class CacheReserveEditResponse: …`

  - `id: CacheReserve`

    The identifier of the caching setting.

    - `"cache_reserve"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Cache Reserve zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.cache_reserve.edit(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    value="on",
)
print(response.id)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "editable": true,
    "id": "cache_reserve",
    "value": "on"
  },
  "success": true
}
```

## Get Cache Reserve Clear

`cache.cache_reserve.status(CacheReserveStatusParams**kwargs)  -> CacheReserveStatusResponse`

**get** `/zones/{zone_id}/cache/cache_reserve_clear`

You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class CacheReserveStatusResponse: …`

  You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.

  - `id: CacheReserveClear`

    ID of the zone setting.

    - `"cache_reserve_clear"`

  - `start_ts: datetime`

    The time that the latest Cache Reserve Clear operation started.

  - `state: State`

    The current state of the Cache Reserve Clear operation.

    - `"In-progress"`

    - `"Completed"`

  - `end_ts: Optional[datetime]`

    The time that the latest Cache Reserve Clear operation completed.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.cache_reserve.status(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(response.id)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "end_ts": "2023-10-02T12:00:00.12345Z",
    "id": "cache_reserve_clear",
    "start_ts": "2023-10-02T10:00:00.12345Z",
    "state": "Completed"
  },
  "success": true
}
```

## Start Cache Reserve Clear

`cache.cache_reserve.clear(CacheReserveClearParams**kwargs)  -> CacheReserveClearResponse`

**post** `/zones/{zone_id}/cache/cache_reserve_clear`

You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.

### Parameters

- `zone_id: str`

  Identifier.

- `body: object`

### Returns

- `class CacheReserveClearResponse: …`

  You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.

  - `id: CacheReserveClear`

    ID of the zone setting.

    - `"cache_reserve_clear"`

  - `start_ts: datetime`

    The time that the latest Cache Reserve Clear operation started.

  - `state: State`

    The current state of the Cache Reserve Clear operation.

    - `"In-progress"`

    - `"Completed"`

  - `end_ts: Optional[datetime]`

    The time that the latest Cache Reserve Clear operation completed.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.cache_reserve.clear(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    body={},
)
print(response.id)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "id": "cache_reserve_clear",
    "start_ts": "2023-10-02T10:00:00.12345Z",
    "state": "In-progress"
  },
  "success": true
}
```

## Domain Types

### Cache Reserve

- `Literal["cache_reserve"]`

  The identifier of the caching setting.

  - `"cache_reserve"`

### Cache Reserve Clear

- `Literal["cache_reserve_clear"]`

  ID of the zone setting.

  - `"cache_reserve_clear"`

### State

- `Literal["In-progress", "Completed"]`

  The current state of the Cache Reserve Clear operation.

  - `"In-progress"`

  - `"Completed"`

### Cache Reserve Get Response

- `class CacheReserveGetResponse: …`

  - `id: CacheReserve`

    The identifier of the caching setting.

    - `"cache_reserve"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Cache Reserve zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Cache Reserve Edit Response

- `class CacheReserveEditResponse: …`

  - `id: CacheReserve`

    The identifier of the caching setting.

    - `"cache_reserve"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Cache Reserve zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Cache Reserve Status Response

- `class CacheReserveStatusResponse: …`

  You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.

  - `id: CacheReserveClear`

    ID of the zone setting.

    - `"cache_reserve_clear"`

  - `start_ts: datetime`

    The time that the latest Cache Reserve Clear operation started.

  - `state: State`

    The current state of the Cache Reserve Clear operation.

    - `"In-progress"`

    - `"Completed"`

  - `end_ts: Optional[datetime]`

    The time that the latest Cache Reserve Clear operation completed.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Cache Reserve Clear Response

- `class CacheReserveClearResponse: …`

  You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.

  - `id: CacheReserveClear`

    ID of the zone setting.

    - `"cache_reserve_clear"`

  - `start_ts: datetime`

    The time that the latest Cache Reserve Clear operation started.

  - `state: State`

    The current state of the Cache Reserve Clear operation.

    - `"In-progress"`

    - `"Completed"`

  - `end_ts: Optional[datetime]`

    The time that the latest Cache Reserve Clear operation completed.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

# Smart Tiered Cache

## Get Smart Tiered Cache setting

`cache.smart_tiered_cache.get(SmartTieredCacheGetParams**kwargs)  -> SmartTieredCacheGetResponse`

**get** `/zones/{zone_id}/cache/tiered_cache_smart_topology_enable`

Smart Tiered Cache dynamically selects the single closest upper tier for each of your website’s origins with no configuration required, using our in-house performance and routing data. Cloudflare collects latency data for each request to an origin, and uses the latency data to determine how well any upper-tier data center is connected with an origin. As a result, Cloudflare can select the data center with the lowest latency to be the upper-tier for an origin.

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class SmartTieredCacheGetResponse: …`

  - `id: Literal["tiered_cache_smart_topology_enable"]`

    The identifier of the caching setting.

    - `"tiered_cache_smart_topology_enable"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Smart Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
smart_tiered_cache = client.cache.smart_tiered_cache.get(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(smart_tiered_cache.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "tiered_cache_smart_topology_enable",
    "editable": true,
    "value": "on",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}
```

## Create Smart Tiered Cache setting

`cache.smart_tiered_cache.create(SmartTieredCacheCreateParams**kwargs)  -> SmartTieredCacheCreateResponse`

**post** `/zones/{zone_id}/cache/tiered_cache_smart_topology_enable`

Smart Tiered Cache dynamically selects the single closest upper tier for each of your website's origins with no configuration required, using our in-house performance and routing data. Cloudflare collects latency data for each request to an origin, and uses the latency data to determine how well any upper-tier data center is connected with an origin. As a result, Cloudflare can select the data center with the lowest latency to be the upper-tier for an origin.

### Parameters

- `zone_id: str`

  Identifier.

- `value: Literal["on", "off"]`

  Enable or disable the Smart Tiered Cache.

  - `"on"`

  - `"off"`

### Returns

- `class SmartTieredCacheCreateResponse: …`

  - `id: Literal["tiered_cache_smart_topology_enable"]`

    The identifier of the caching setting.

    - `"tiered_cache_smart_topology_enable"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Smart Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
smart_tiered_cache = client.cache.smart_tiered_cache.create(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    value="on",
)
print(smart_tiered_cache.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "tiered_cache_smart_topology_enable",
    "editable": true,
    "value": "on",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}
```

## Patch Smart Tiered Cache setting

`cache.smart_tiered_cache.edit(SmartTieredCacheEditParams**kwargs)  -> SmartTieredCacheEditResponse`

**patch** `/zones/{zone_id}/cache/tiered_cache_smart_topology_enable`

Smart Tiered Cache dynamically selects the single closest upper tier for each of your website’s origins with no configuration required, using our in-house performance and routing data. Cloudflare collects latency data for each request to an origin, and uses the latency data to determine how well any upper-tier data center is connected with an origin. As a result, Cloudflare can select the data center with the lowest latency to be the upper-tier for an origin.

### Parameters

- `zone_id: str`

  Identifier.

- `value: Literal["on", "off"]`

  Enable or disable the Smart Tiered Cache.

  - `"on"`

  - `"off"`

### Returns

- `class SmartTieredCacheEditResponse: …`

  - `id: Literal["tiered_cache_smart_topology_enable"]`

    The identifier of the caching setting.

    - `"tiered_cache_smart_topology_enable"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Smart Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.smart_tiered_cache.edit(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    value="on",
)
print(response.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "tiered_cache_smart_topology_enable",
    "editable": true,
    "value": "on",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}
```

## Delete Smart Tiered Cache setting

`cache.smart_tiered_cache.delete(SmartTieredCacheDeleteParams**kwargs)  -> SmartTieredCacheDeleteResponse`

**delete** `/zones/{zone_id}/cache/tiered_cache_smart_topology_enable`

Smart Tiered Cache dynamically selects the single closest upper tier for each of your website’s origins with no configuration required, using our in-house performance and routing data. Cloudflare collects latency data for each request to an origin, and uses the latency data to determine how well any upper-tier data center is connected with an origin. As a result, Cloudflare can select the data center with the lowest latency to be the upper-tier for an origin.

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class SmartTieredCacheDeleteResponse: …`

  - `id: Literal["tiered_cache_smart_topology_enable"]`

    The identifier of the caching setting.

    - `"tiered_cache_smart_topology_enable"`

  - `editable: bool`

    Whether the setting is editable.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
smart_tiered_cache = client.cache.smart_tiered_cache.delete(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(smart_tiered_cache.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "tiered_cache_smart_topology_enable",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}
```

## Domain Types

### Smart Tiered Cache Get Response

- `class SmartTieredCacheGetResponse: …`

  - `id: Literal["tiered_cache_smart_topology_enable"]`

    The identifier of the caching setting.

    - `"tiered_cache_smart_topology_enable"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Smart Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Smart Tiered Cache Create Response

- `class SmartTieredCacheCreateResponse: …`

  - `id: Literal["tiered_cache_smart_topology_enable"]`

    The identifier of the caching setting.

    - `"tiered_cache_smart_topology_enable"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Smart Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Smart Tiered Cache Edit Response

- `class SmartTieredCacheEditResponse: …`

  - `id: Literal["tiered_cache_smart_topology_enable"]`

    The identifier of the caching setting.

    - `"tiered_cache_smart_topology_enable"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Smart Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Smart Tiered Cache Delete Response

- `class SmartTieredCacheDeleteResponse: …`

  - `id: Literal["tiered_cache_smart_topology_enable"]`

    The identifier of the caching setting.

    - `"tiered_cache_smart_topology_enable"`

  - `editable: bool`

    Whether the setting is editable.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

# Variants

## Get variants setting

`cache.variants.get(VariantGetParams**kwargs)  -> VariantGetResponse`

**get** `/zones/{zone_id}/cache/variants`

Variant support enables caching variants of images with certain file extensions in addition to the original. This only applies when the origin server sends the 'Vary: Accept' response header. If the origin server sends 'Vary: Accept' but does not serve the variant requested, the response will not be cached. This will be indicated with BYPASS cache status in the response headers.

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class VariantGetResponse: …`

  - `id: Literal["variants"]`

    The identifier of the caching setting.

    - `"variants"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Value`

    Value of the zone setting.

    - `avif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for avif.

    - `bmp: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for bmp.

    - `gif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for gif.

    - `jp2: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jp2.

    - `jpeg: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpeg.

    - `jpg: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpg.

    - `jpg2: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpg2.

    - `png: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for png.

    - `tif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for tif.

    - `tiff: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for tiff.

    - `webp: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for webp.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
variant = client.cache.variants.get(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(variant.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "variants",
    "editable": true,
    "value": {
      "avif": [
        "image/webp",
        "image/jpeg"
      ],
      "bmp": [
        "image/webp",
        "image/jpeg"
      ],
      "gif": [
        "image/webp",
        "image/jpeg"
      ],
      "jp2": [
        "image/webp",
        "image/avif"
      ],
      "jpeg": [
        "image/webp",
        "image/avif"
      ],
      "jpg": [
        "image/webp",
        "image/avif"
      ],
      "jpg2": [
        "image/webp",
        "image/avif"
      ],
      "png": [
        "image/webp",
        "image/avif"
      ],
      "tif": [
        "image/webp",
        "image/avif"
      ],
      "tiff": [
        "image/webp",
        "image/avif"
      ],
      "webp": [
        "image/jpeg",
        "image/avif"
      ]
    },
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}
```

## Change variants setting

`cache.variants.edit(VariantEditParams**kwargs)  -> VariantEditResponse`

**patch** `/zones/{zone_id}/cache/variants`

Variant support enables caching variants of images with certain file extensions in addition to the original. This only applies when the origin server sends the 'Vary: Accept' response header. If the origin server sends 'Vary: Accept' but does not serve the variant requested, the response will not be cached. This will be indicated with BYPASS cache status in the response headers.

### Parameters

- `zone_id: str`

  Identifier.

- `value: Value`

  Value of the zone setting.

  - `avif: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for avif.

  - `bmp: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for bmp.

  - `gif: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for gif.

  - `jp2: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for jp2.

  - `jpeg: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for jpeg.

  - `jpg: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for jpg.

  - `jpg2: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for jpg2.

  - `png: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for png.

  - `tif: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for tif.

  - `tiff: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for tiff.

  - `webp: Optional[Sequence[str]]`

    List of strings with the MIME types of all the variants that should be served for webp.

### Returns

- `class VariantEditResponse: …`

  - `id: Literal["variants"]`

    The identifier of the caching setting.

    - `"variants"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Value`

    Value of the zone setting.

    - `avif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for avif.

    - `bmp: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for bmp.

    - `gif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for gif.

    - `jp2: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jp2.

    - `jpeg: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpeg.

    - `jpg: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpg.

    - `jpg2: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpg2.

    - `png: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for png.

    - `tif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for tif.

    - `tiff: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for tiff.

    - `webp: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for webp.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.variants.edit(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    value={},
)
print(response.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "variants",
    "editable": true,
    "value": {
      "avif": [
        "image/webp",
        "image/jpeg"
      ],
      "bmp": [
        "image/webp",
        "image/jpeg"
      ],
      "gif": [
        "image/webp",
        "image/jpeg"
      ],
      "jp2": [
        "image/webp",
        "image/avif"
      ],
      "jpeg": [
        "image/webp",
        "image/avif"
      ],
      "jpg": [
        "image/webp",
        "image/avif"
      ],
      "jpg2": [
        "image/webp",
        "image/avif"
      ],
      "png": [
        "image/webp",
        "image/avif"
      ],
      "tif": [
        "image/webp",
        "image/avif"
      ],
      "tiff": [
        "image/webp",
        "image/avif"
      ],
      "webp": [
        "image/jpeg",
        "image/avif"
      ]
    },
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}
```

## Delete variants setting

`cache.variants.delete(VariantDeleteParams**kwargs)  -> VariantDeleteResponse`

**delete** `/zones/{zone_id}/cache/variants`

Variant support enables caching variants of images with certain file extensions in addition to the original. This only applies when the origin server sends the 'Vary: Accept' response header. If the origin server sends 'Vary: Accept' but does not serve the variant requested, the response will not be cached. This will be indicated with BYPASS cache status in the response headers.

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class VariantDeleteResponse: …`

  - `id: Literal["variants"]`

    The identifier of the caching setting.

    - `"variants"`

  - `editable: bool`

    Whether the setting is editable.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
variant = client.cache.variants.delete(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(variant.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "variants",
    "editable": true,
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}
```

## Domain Types

### Cache Variant

- `class CacheVariant: …`

  Variant support enables caching variants of images with certain file extensions in addition to the original. This only applies when the origin server sends the 'Vary: Accept' response header. If the origin server sends 'Vary: Accept' but does not serve the variant requested, the response will not be cached. This will be indicated with BYPASS cache status in the response headers.

  - `id: Literal["variants"]`

    ID of the zone setting.

    - `"variants"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Variant Get Response

- `class VariantGetResponse: …`

  - `id: Literal["variants"]`

    The identifier of the caching setting.

    - `"variants"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Value`

    Value of the zone setting.

    - `avif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for avif.

    - `bmp: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for bmp.

    - `gif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for gif.

    - `jp2: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jp2.

    - `jpeg: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpeg.

    - `jpg: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpg.

    - `jpg2: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpg2.

    - `png: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for png.

    - `tif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for tif.

    - `tiff: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for tiff.

    - `webp: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for webp.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Variant Edit Response

- `class VariantEditResponse: …`

  - `id: Literal["variants"]`

    The identifier of the caching setting.

    - `"variants"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Value`

    Value of the zone setting.

    - `avif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for avif.

    - `bmp: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for bmp.

    - `gif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for gif.

    - `jp2: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jp2.

    - `jpeg: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpeg.

    - `jpg: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpg.

    - `jpg2: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for jpg2.

    - `png: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for png.

    - `tif: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for tif.

    - `tiff: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for tiff.

    - `webp: Optional[List[str]]`

      List of strings with the MIME types of all the variants that should be served for webp.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Variant Delete Response

- `class VariantDeleteResponse: …`

  - `id: Literal["variants"]`

    The identifier of the caching setting.

    - `"variants"`

  - `editable: bool`

    Whether the setting is editable.

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

# Regional Tiered Cache

## Get Regional Tiered Cache setting

`cache.regional_tiered_cache.get(RegionalTieredCacheGetParams**kwargs)  -> RegionalTieredCacheGetResponse`

**get** `/zones/{zone_id}/cache/regional_tiered_cache`

Instructs Cloudflare to check a regional hub data center on the way to your upper tier. This can help improve performance for smart and custom tiered cache topologies.

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class RegionalTieredCacheGetResponse: …`

  - `id: RegionalTieredCache`

    The identifier of the caching setting.

    - `"tc_regional"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Regional Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
regional_tiered_cache = client.cache.regional_tiered_cache.get(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(regional_tiered_cache.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "tc_regional",
    "editable": true,
    "value": "on",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}
```

## Change Regional Tiered Cache setting

`cache.regional_tiered_cache.edit(RegionalTieredCacheEditParams**kwargs)  -> RegionalTieredCacheEditResponse`

**patch** `/zones/{zone_id}/cache/regional_tiered_cache`

Instructs Cloudflare to check a regional hub data center on the way to your upper tier. This can help improve performance for smart and custom tiered cache topologies.

### Parameters

- `zone_id: str`

  Identifier.

- `value: Literal["on", "off"]`

  Value of the Regional Tiered Cache zone setting.

  - `"on"`

  - `"off"`

### Returns

- `class RegionalTieredCacheEditResponse: …`

  - `id: RegionalTieredCache`

    The identifier of the caching setting.

    - `"tc_regional"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Regional Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.regional_tiered_cache.edit(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    value="on",
)
print(response.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "tc_regional",
    "editable": true,
    "value": "on",
    "modified_on": "2014-01-01T05:20:00.12345Z"
  }
}
```

## Domain Types

### Regional Tiered Cache

- `Literal["tc_regional"]`

  The identifier of the caching setting.

  - `"tc_regional"`

### Regional Tiered Cache Get Response

- `class RegionalTieredCacheGetResponse: …`

  - `id: RegionalTieredCache`

    The identifier of the caching setting.

    - `"tc_regional"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Regional Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

### Regional Tiered Cache Edit Response

- `class RegionalTieredCacheEditResponse: …`

  - `id: RegionalTieredCache`

    The identifier of the caching setting.

    - `"tc_regional"`

  - `editable: bool`

    Whether the setting is editable.

  - `value: Literal["on", "off"]`

    Value of the Regional Tiered Cache zone setting.

    - `"on"`

    - `"off"`

  - `modified_on: Optional[datetime]`

    Last time this setting was modified.

# Origin Cloud Regions

## List origin cloud region mappings

`cache.origin_cloud_regions.list(OriginCloudRegionListParams**kwargs)  -> SyncV4PagePaginationArray[OriginCloudRegion]`

**get** `/zones/{zone_id}/origin/cloud_regions`

Returns all IP-to-cloud-region mappings configured for the zone with pagination support. Each mapping tells Cloudflare which cloud vendor and region hosts the origin at that IP, enabling the edge to route via the nearest Tiered Cache upper-tier co-located with that cloud provider. Returns an empty array when no mappings exist.

### Parameters

- `zone_id: str`

  Identifier.

- `page: Optional[int]`

  Page number of paginated results.

- `per_page: Optional[int]`

  Number of items per page.

### Returns

- `class OriginCloudRegion: …`

  A single origin IP-to-cloud-region mapping.

  - `origin_ip: str`

    The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for IPv6).

  - `region: str`

    Cloud vendor region identifier.

  - `vendor: Literal["aws", "azure", "gcp", "oci"]`

    Cloud vendor hosting the origin.

    - `"aws"`

    - `"azure"`

    - `"gcp"`

    - `"oci"`

  - `modified_on: Optional[datetime]`

    Time this mapping was last modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.cache.origin_cloud_regions.list(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
page = page.result[0]
print(page.origin_ip)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": [],
  "result_info": {
    "count": 0,
    "page": 1,
    "per_page": 20,
    "total_count": 0,
    "total_pages": 0
  },
  "success": true
}
```

## Get an origin cloud region mapping

`cache.origin_cloud_regions.get(strorigin_ip, OriginCloudRegionGetParams**kwargs)  -> OriginCloudRegion`

**get** `/zones/{zone_id}/origin/cloud_regions/{origin_ip}`

Returns the cloud region mapping for a single origin IP address. The IP path parameter is normalized before lookup (RFC 5952 for IPv6). Returns 404 if the zone has no mappings or if the specified IP has no mapping.

### Parameters

- `zone_id: str`

  Identifier.

- `origin_ip: str`

### Returns

- `class OriginCloudRegion: …`

  A single origin IP-to-cloud-region mapping.

  - `origin_ip: str`

    The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for IPv6).

  - `region: str`

    Cloud vendor region identifier.

  - `vendor: Literal["aws", "azure", "gcp", "oci"]`

    Cloud vendor hosting the origin.

    - `"aws"`

    - `"azure"`

    - `"gcp"`

    - `"oci"`

  - `modified_on: Optional[datetime]`

    Time this mapping was last modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
origin_cloud_region = client.cache.origin_cloud_regions.get(
    origin_ip="192.0.2.1",
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(origin_cloud_region.origin_ip)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "modified_on": "2026-03-01T12:00:00Z",
    "origin_ip": "192.0.2.1",
    "region": "us-east-1",
    "vendor": "aws"
  },
  "success": true
}
```

## Create or replace an origin cloud region mapping

`cache.origin_cloud_regions.update(strpath_origin_ip, OriginCloudRegionUpdateParams**kwargs)  -> OriginCloudRegion`

**put** `/zones/{zone_id}/origin/cloud_regions/{origin_ip}`

Creates a new IP-to-cloud-region mapping or replaces the existing mapping for the specified IP. PUT is idempotent — calling it repeatedly with the same body produces the same result. The IP path parameter is normalized to canonical form (RFC 5952 for IPv6) before storage. The vendor and region are validated against the list from `GET /zones/{zone_id}/origin/cloud_regions/supported_regions`. Returns 400 if the `origin_ip` in the body does not match the URL path parameter. Returns 403 (code 1164) when the zone has reached the limit of 3,500 IP mappings.

### Parameters

- `zone_id: str`

  Identifier.

- `origin_ip: str`

- `origin_ip: str`

- `region: str`

  Cloud vendor region identifier. Must be a valid region for the specified vendor as returned by the supported_regions endpoint.

- `vendor: Literal["aws", "azure", "gcp", "oci"]`

  Cloud vendor hosting the origin. Must be one of the supported vendors.

  - `"aws"`

  - `"azure"`

  - `"gcp"`

  - `"oci"`

### Returns

- `class OriginCloudRegion: …`

  A single origin IP-to-cloud-region mapping.

  - `origin_ip: str`

    The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for IPv6).

  - `region: str`

    Cloud vendor region identifier.

  - `vendor: Literal["aws", "azure", "gcp", "oci"]`

    Cloud vendor hosting the origin.

    - `"aws"`

    - `"azure"`

    - `"gcp"`

    - `"oci"`

  - `modified_on: Optional[datetime]`

    Time this mapping was last modified.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
origin_cloud_region = client.cache.origin_cloud_regions.update(
    path_origin_ip="192.0.2.1",
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    body_origin_ip="192.0.2.1",
    region="us-east-1",
    vendor="aws",
)
print(origin_cloud_region.origin_ip)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "modified_on": "2026-03-01T12:00:00Z",
    "origin_ip": "192.0.2.1",
    "region": "us-east-1",
    "vendor": "aws"
  },
  "success": true
}
```

## Delete an origin cloud region mapping

`cache.origin_cloud_regions.delete(strorigin_ip, OriginCloudRegionDeleteParams**kwargs)  -> OriginCloudRegionDeleteResponse`

**delete** `/zones/{zone_id}/origin/cloud_regions/{origin_ip}`

Removes the cloud region mapping for a single origin IP address. The IP path parameter is normalized before lookup. Returns the deleted IP on success. Returns 404 if no mapping exists for the specified IP. When the last mapping for the zone is removed the underlying rule record is also deleted.

### Parameters

- `zone_id: str`

  Identifier.

- `origin_ip: str`

### Returns

- `class OriginCloudRegionDeleteResponse: …`

  Response result for a delete operation. Identifies the deleted mapping.

  - `origin_ip: str`

    The origin IP address whose mapping was deleted.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
origin_cloud_region = client.cache.origin_cloud_regions.delete(
    origin_ip="192.0.2.1",
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(origin_cloud_region.origin_ip)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "origin_ip": "192.0.2.1"
  },
  "success": true
}
```

## Batch create or replace origin cloud region mappings

`cache.origin_cloud_regions.bulk_update(OriginCloudRegionBulkUpdateParams**kwargs)  -> OriginCloudRegionBulkUpdateResponse`

**put** `/zones/{zone_id}/origin/cloud_regions/batch`

Upserts up to 100 IP-to-cloud-region mappings in a single request. Items in the request body are created or replaced; mappings not included in the request body are preserved unchanged (this is a merge operation, not a full collection replacement). Each item is validated independently — valid items are applied and invalid items are returned in the `failed` array. The vendor and region for every item are validated against the list from `GET /zones/{zone_id}/origin/cloud_regions/supported_regions`.

### Parameters

- `zone_id: str`

  Identifier.

- `body: Iterable[Body]`

  - `origin_ip: str`

    Origin IP address (IPv4 or IPv6). For the single PUT endpoint (`PUT /origin/cloud_regions/{origin_ip}`), this field must match the path parameter or the request will be rejected with a 400 error. For the batch PUT endpoint, this field identifies which mapping to upsert.

  - `region: str`

    Cloud vendor region identifier. Must be a valid region for the specified vendor as returned by the supported_regions endpoint.

  - `vendor: Literal["aws", "azure", "gcp", "oci"]`

    Cloud vendor hosting the origin. Must be one of the supported vendors.

    - `"aws"`

    - `"azure"`

    - `"gcp"`

    - `"oci"`

### Returns

- `class OriginCloudRegionBulkUpdateResponse: …`

  Response result for a batch origin cloud region operation.

  - `failed: List[Failed]`

    Items that could not be applied, with error details.

    - `origin_ip: str`

      The origin IP address for this item.

    - `error: Optional[str]`

      Error message explaining why the item failed. Present only on failed items.

    - `region: Optional[str]`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `vendor: Optional[str]`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

  - `succeeded: List[Succeeded]`

    Items that were successfully applied.

    - `origin_ip: str`

      The origin IP address for this item.

    - `error: Optional[str]`

      Error message explaining why the item failed. Present only on failed items.

    - `region: Optional[str]`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `vendor: Optional[str]`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.origin_cloud_regions.bulk_update(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    body=[{
        "origin_ip": "192.0.2.1",
        "region": "us-east-1",
        "vendor": "aws",
    }, {
        "origin_ip": "2001:db8::1",
        "region": "us-central1",
        "vendor": "gcp",
    }],
)
print(response.failed)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "failed": [],
    "succeeded": [
      {
        "origin_ip": "192.0.2.1",
        "region": "us-east-1",
        "vendor": "aws"
      },
      {
        "origin_ip": "2001:db8::1",
        "region": "us-central1",
        "vendor": "gcp"
      }
    ]
  },
  "success": true
}
```

## Batch delete origin cloud region mappings

`cache.origin_cloud_regions.bulk_delete(OriginCloudRegionBulkDeleteParams**kwargs)  -> OriginCloudRegionBulkDeleteResponse`

**delete** `/zones/{zone_id}/origin/cloud_regions/batch`

Removes up to 100 IP-to-cloud-region mappings in a single request. Each IP is validated independently — successfully deleted items are returned in the `succeeded` array and IPs that could not be found or are invalid are returned in the `failed` array.

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class OriginCloudRegionBulkDeleteResponse: …`

  Response result for a batch origin cloud region operation.

  - `failed: List[Failed]`

    Items that could not be applied, with error details.

    - `origin_ip: str`

      The origin IP address for this item.

    - `error: Optional[str]`

      Error message explaining why the item failed. Present only on failed items.

    - `region: Optional[str]`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `vendor: Optional[str]`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

  - `succeeded: List[Succeeded]`

    Items that were successfully applied.

    - `origin_ip: str`

      The origin IP address for this item.

    - `error: Optional[str]`

      Error message explaining why the item failed. Present only on failed items.

    - `region: Optional[str]`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `vendor: Optional[str]`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.origin_cloud_regions.bulk_delete(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(response.failed)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "failed": [],
    "succeeded": [
      {
        "origin_ip": "192.0.2.1",
        "region": "us-east-1",
        "vendor": "aws"
      },
      {
        "origin_ip": "2001:db8::1",
        "region": "us-central1",
        "vendor": "gcp"
      }
    ]
  },
  "success": true
}
```

## List supported cloud vendors and regions

`cache.origin_cloud_regions.supported_regions(OriginCloudRegionSupportedRegionsParams**kwargs)  -> OriginCloudRegionSupportedRegionsResponse`

**get** `/zones/{zone_id}/origin/cloud_regions/supported_regions`

Returns the cloud vendors and regions that are valid values for origin cloud region mappings. Each region includes the Tiered Cache upper-tier colocation codes that will be used for cache routing when a mapping targeting that region is active. Requires the zone to have Tiered Cache enabled.

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class OriginCloudRegionSupportedRegionsResponse: …`

  Cloud vendors and their supported regions for origin cloud region mappings.

  - `obtained_codes: bool`

    Whether Cloudflare airport codes (IATA colo identifiers) were successfully resolved for the `upper_tier_colos` field on each region. When `false`, the `upper_tier_colos` arrays may be empty or incomplete.

  - `vendors: Dict[str, List[Vendor]]`

    Map of vendor name to list of supported regions.

    - `name: str`

      Cloud vendor region identifier.

    - `upper_tier_colos: List[str]`

      Cloudflare Tiered Cache upper-tier colocation codes co-located with this cloud region. Requests from zones with a matching origin mapping will be routed through these colos.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.cache.origin_cloud_regions.supported_regions(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(response.obtained_codes)
```

#### Response

```json
{
  "errors": [],
  "messages": [],
  "result": {
    "obtained_codes": true,
    "vendors": {
      "aws": [
        {
          "name": "us-east-1",
          "upper_tier_colos": [
            "IAD",
            "EWR"
          ]
        },
        {
          "name": "us-west-2",
          "upper_tier_colos": [
            "SEA"
          ]
        }
      ],
      "gcp": [
        {
          "name": "us-central1",
          "upper_tier_colos": [
            "ORD"
          ]
        }
      ]
    }
  },
  "success": true
}
```

## Domain Types

### Origin Cloud Region

- `class OriginCloudRegion: …`

  A single origin IP-to-cloud-region mapping.

  - `origin_ip: str`

    The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for IPv6).

  - `region: str`

    Cloud vendor region identifier.

  - `vendor: Literal["aws", "azure", "gcp", "oci"]`

    Cloud vendor hosting the origin.

    - `"aws"`

    - `"azure"`

    - `"gcp"`

    - `"oci"`

  - `modified_on: Optional[datetime]`

    Time this mapping was last modified.

### Origin Cloud Region Delete Response

- `class OriginCloudRegionDeleteResponse: …`

  Response result for a delete operation. Identifies the deleted mapping.

  - `origin_ip: str`

    The origin IP address whose mapping was deleted.

### Origin Cloud Region Bulk Update Response

- `class OriginCloudRegionBulkUpdateResponse: …`

  Response result for a batch origin cloud region operation.

  - `failed: List[Failed]`

    Items that could not be applied, with error details.

    - `origin_ip: str`

      The origin IP address for this item.

    - `error: Optional[str]`

      Error message explaining why the item failed. Present only on failed items.

    - `region: Optional[str]`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `vendor: Optional[str]`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

  - `succeeded: List[Succeeded]`

    Items that were successfully applied.

    - `origin_ip: str`

      The origin IP address for this item.

    - `error: Optional[str]`

      Error message explaining why the item failed. Present only on failed items.

    - `region: Optional[str]`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `vendor: Optional[str]`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

### Origin Cloud Region Bulk Delete Response

- `class OriginCloudRegionBulkDeleteResponse: …`

  Response result for a batch origin cloud region operation.

  - `failed: List[Failed]`

    Items that could not be applied, with error details.

    - `origin_ip: str`

      The origin IP address for this item.

    - `error: Optional[str]`

      Error message explaining why the item failed. Present only on failed items.

    - `region: Optional[str]`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `vendor: Optional[str]`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

  - `succeeded: List[Succeeded]`

    Items that were successfully applied.

    - `origin_ip: str`

      The origin IP address for this item.

    - `error: Optional[str]`

      Error message explaining why the item failed. Present only on failed items.

    - `region: Optional[str]`

      Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

    - `vendor: Optional[str]`

      Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).

### Origin Cloud Region Supported Regions Response

- `class OriginCloudRegionSupportedRegionsResponse: …`

  Cloud vendors and their supported regions for origin cloud region mappings.

  - `obtained_codes: bool`

    Whether Cloudflare airport codes (IATA colo identifiers) were successfully resolved for the `upper_tier_colos` field on each region. When `false`, the `upper_tier_colos` arrays may be empty or incomplete.

  - `vendors: Dict[str, List[Vendor]]`

    Map of vendor name to list of supported regions.

    - `name: str`

      Cloud vendor region identifier.

    - `upper_tier_colos: List[str]`

      Cloudflare Tiered Cache upper-tier colocation codes co-located with this cloud region. Requests from zones with a matching origin mapping will be routed through these colos.