> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Endpoint Cache Settings

> Updates cache settings for a specific endpoint/method. Endpoint-level cache settings override API Proxy-level cache settings for the specific endpoint.

## Endpoint

```
PATCH /apiops/projects/{projectName}/apiProxies/{apiProxyName}/endpoints/cache/
```

## Authentication

Requires a Personal API Access Token.

### Header

```
Authorization: Bearer YOUR_TOKEN
```

## Request

### Headers

| Header        | Value            | Required |
| ------------- | ---------------- | -------- |
| Authorization | Bearer {token}   | Yes      |
| Content-Type  | application/json | Yes      |

### Path Parameters

| Parameter    | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| projectName  | string | Yes      | Project name   |
| apiProxyName | string | Yes      | API Proxy name |

### Request Body

The request body includes endpoint identifier and `CacheSettings` structure. See [Update Cache Settings](/api-reference/api-proxies/settings/update-cache-settings) for detailed cache settings field descriptions.

#### Full JSON Body Example - Basic Cache Configuration

```json theme={null}
{
  "identifierName": "/api/users",
  "identifierHttpMethod": "GET",
  "cacheSettings": {
    "name": "Endpoint Cache Settings",
    "description": "Cache configuration for this endpoint",
    "cacheActive": true,
    "cacheOnlyHttpGetRequests": false,
    "cacheKeyType": "QUERY_PARAMS",
    "cacheStorageType": "LOCAL",
    "capacity": 1000,
    "ttl": 3600,
    "handlingAction": "STOP",
    "invalidationRequiresAuthn": false,
    "cacheNullValue": false,
    "variableList": []
  },
  "deploy": false,
  "deployTargetEnvironmentNameList": []
}
```

#### Full JSON Body Example - Custom Cache Key

```json theme={null}
{
  "identifierName": "/api/users",
  "identifierHttpMethod": "GET",
  "cacheSettings": {
    "name": "Endpoint Cache with Custom Key",
    "description": "Cache using custom variables",
    "cacheActive": true,
    "cacheOnlyHttpGetRequests": false,
    "cacheKeyType": "CUSTOM",
    "cacheStorageType": "DISTRIBUTED",
    "capacity": 5000,
    "ttl": 7200,
    "handlingAction": "CONTINUE",
    "invalidationRequiresAuthn": true,
    "cacheNullValue": true,
    "variableList": [
      {
        "name": "userId",
        "type": "HEADER",
        "dataType": "STRING"
      },
      {
        "name": "apiVersion",
        "type": "PARAMETER",
        "dataType": "STRING"
      }
    ]
  }
}
```

#### Request Body Fields

| Field                           | Type           | Required | Default | Description                                                                                                       |
| ------------------------------- | -------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| identifierName                  | string         | Yes      | -       | Endpoint path/name (used to identify the endpoint)                                                                |
| identifierHttpMethod            | string         | Yes      | -       | HTTP method for the endpoint (used to identify the endpoint). See [EnumHttpRequestMethod](#enumhttprequestmethod) |
| cacheSettings                   | object         | Yes      | -       | Cache settings object (see fields below)                                                                          |
| deploy                          | boolean        | No       | false   | If true, deploy the API proxy after saving changes                                                                |
| deployTargetEnvironmentNameList | array\[string] | No       | -       | List of environment names to deploy to (required when deploy=true)                                                |

#### Cache Settings Object Fields

| Field                     | Type    | Required | Default       | Description                                                                                                                             |
| ------------------------- | ------- | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| name                      | string  | Yes      | -             | Cache settings name                                                                                                                     |
| description               | string  | No       | -             | Cache settings description                                                                                                              |
| cacheActive               | boolean | No       | false         | Enable/disable cache for this endpoint                                                                                                  |
| cacheOnlyHttpGetRequests  | boolean | No       | true          | Cache only GET requests (if false, caches all methods)                                                                                  |
| cacheKeyType              | string  | No       | QUERY\_PARAMS | Cache key type. See [EnumCacheKeyType](#enumcachekeytype)                                                                               |
| cacheStorageType          | string  | No       | DISTRIBUTED   | Cache storage type. See [EnumCacheStorageType](#enumcachestoragetype)                                                                   |
| capacity                  | integer | No       | -             | Maximum cache capacity (number of entries)                                                                                              |
| ttl                       | integer | No       | -             | Time to live in seconds                                                                                                                 |
| handlingAction            | string  | Yes      | -             | Cache handling action when cache hit occurs. See [EnumCacheHandlingAction](#enumcachehandlingaction)                                    |
| invalidationRequiresAuthn | boolean | No       | false         | Require authentication for cache invalidation                                                                                           |
| cacheNullValue            | boolean | No       | false         | Cache null/empty responses                                                                                                              |
| variableList              | array   | No       | \[]           | List of variables for custom cache key (if cacheKeyType=CUSTOM). See [Variable Definition](/api-reference/appendix/variable-definition) |

### EnumCacheKeyType (cacheKeyType)

* `QUERY_PARAMS` - Use query parameters as cache key
* `CUSTOM` - Use custom variables as cache key (requires variableList)

### EnumCacheStorageType (cacheStorageType)

* `LOCAL` - Local cache (per worker instance)
* `DISTRIBUTED` - Distributed cache (shared across all workers)

### EnumCacheHandlingAction (handlingAction)

* `CONTINUE` - Return cached response and continue to backend (for logging/monitoring)
* `STOP` - Return cached response and stop (do not call backend)

## Response

### Success Response (200 OK)

```json theme={null}
{
  "success": true
}
```

When `deploy=true` is specified:

```json theme={null}
{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}
```

#### Response Fields

| Field                              | Type    | Description                                       |
| ---------------------------------- | ------- | ------------------------------------------------- |
| success                            | boolean | Indicates if the request was successful           |
| deploymentResult                   | object  | Deployment result (only present when deploy=true) |
| deploymentResult.success           | boolean | Whether the overall deployment was successful     |
| deploymentResult.deploymentResults | array   | Per-environment deployment results                |

### Error Response (400 Bad Request)

```json theme={null}
{
  "error": "bad_request",
  "error_description": "handlingAction is required"
}
```

#### Common Causes

* Missing required field `handlingAction`
* Invalid enum values
* Invalid cache configuration
* Invalid variableList when cacheKeyType=CUSTOM

### Error Response (401 Unauthorized)

```json theme={null}
{
  "error": "unauthorized_client",
  "error_description": "Invalid token"
}
```

### Error Response (404 Not Found)

```json theme={null}
{
  "error": "not_found",
  "error_description": "ApiProxy (name: MyAPI) was not found!"
}
```

or

```json theme={null}
{
  "error": "not_found",
  "error_description": "Endpoint with name (/api/users) and HTTP method (GET) is not found!"
}
```

## cURL Example

### Example 1: Basic Endpoint Cache Configuration

```bash theme={null}
curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/endpoints/cache/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifierName": "/api/users",
    "identifierHttpMethod": "GET",
    "cacheSettings": {
      "name": "Endpoint Cache Settings",
      "cacheActive": true,
      "cacheOnlyHttpGetRequests": false,
      "cacheKeyType": "QUERY_PARAMS",
      "cacheStorageType": "LOCAL",
      "capacity": 1000,
      "ttl": 3600,
      "handlingAction": "STOP",
      "cacheNullValue": false
    }
  }'
```

### Example 2: Custom Cache Key with Variables

```bash theme={null}
curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/endpoints/cache/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifierName": "/api/users",
    "identifierHttpMethod": "GET",
    "cacheSettings": {
      "name": "Endpoint Cache with Custom Key",
      "cacheActive": true,
      "cacheKeyType": "CUSTOM",
      "cacheStorageType": "DISTRIBUTED",
      "capacity": 5000,
      "ttl": 7200,
      "handlingAction": "CONTINUE",
      "invalidationRequiresAuthn": true,
      "variableList": [
        {
          "name": "userId",
          "type": "HEADER",
          "dataType": "STRING"
        },
        {
          "name": "apiVersion",
          "type": "PARAMETER",
          "dataType": "STRING"
        }
      ]
    }
  }'
```

### Example 3: Save and Deploy

```bash theme={null}
curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/endpoints/cache/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifierName": "/api/users",
    "identifierHttpMethod": "GET",
    "cacheSettings": {
      "name": "Endpoint Cache Settings",
      "cacheActive": true,
      "cacheKeyType": "QUERY_PARAMS",
      "cacheStorageType": "LOCAL",
      "capacity": 1000,
      "ttl": 3600,
      "handlingAction": "STOP"
    },
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"]
  }'
```

## Notes and Warnings

* **Endpoint-Level Override**:
  * Endpoint cache settings override API Proxy-level cache settings
  * If endpoint cache is disabled, API Proxy-level cache still applies
* **handlingAction**:
  * Required field
  * `CONTINUE` - Returns cached response but still calls backend (useful for logging/monitoring)
  * `STOP` - Returns cached response without calling backend (better performance)
* **Cache Key**:
  * When `cacheKeyType=CUSTOM`, provide `variableList` to define cache key components
  * Variables are combined to create unique cache keys
* **Storage Type**:
  * `LOCAL` cache is faster but not shared across workers
  * `DISTRIBUTED` cache is shared across all workers (recommended for multi-instance deployments)
* **TTL**:
  * Cache entries expire after TTL seconds
  * Set appropriate TTL based on data freshness requirements
* **Capacity**:
  * Maximum number of cache entries
  * Older entries are evicted when limit is reached (LRU eviction)
* **GET Only**:
  * When `cacheOnlyHttpGetRequests=true`, only GET requests are cached
  * When `cacheOnlyHttpGetRequests=false`, all HTTP methods can be cached (use with caution)
* **Null Values**:
  * When `cacheNullValue=false`, null/empty responses are not cached
  * When `cacheNullValue=true`, null/empty responses are cached (may cache error responses)
* **Endpoint Validation**:
  * Endpoint must exist in the API Proxy
  * Endpoint is identified by `identifierName` and `identifierHttpMethod` combination (not by ID)
* **Deploy**: When `deploy=true`, the API proxy is automatically deployed to the specified environments after saving

## Permissions

User must have **`API_MANAGEMENT` + `MANAGE`** permission in the project.

## Related Documentation

* [Update Cache Settings](/api-reference/api-proxies/settings/update-cache-settings) - Update API Proxy-level cache settings
* [Get Endpoint](/api-reference/api-proxies/endpoints/get-endpoint) - Get endpoint details
* [List Endpoints](/api-reference/api-proxies/endpoints/list-endpoints) - List all endpoints
* [Update Endpoint](/api-reference/api-proxies/endpoints/update-endpoint) - Update endpoint configuration