> ## 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 Policy

> Updates an existing policy in an API Proxy. The policy can be updated with new configuration, moved to a different position in the pipeline, or moved to a different scope/pipeline.

## Endpoint

```plaintext theme={null}
PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/
```

## Authentication

Requires a Personal API Access Token.

### Header

```plaintext theme={null}
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           |
| policyName   | string | Yes      | Policy name (must exist) |

### Request Body

#### Full JSON Body Example

```json theme={null}
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 2
  },
  "policy": {
    "type": "policy-api-based-throttling",
    "description": "Updated API throttling policy - 200 requests per minute",
    "active": true,
    "targetVariableForIdentity": {
      "type": "HEADER",
      "headerName": "X-API-Key"
    },
    "messageCountForInterval": 200,
    "throttlingInterval": "ONE_MINUTE",
    "intervalPeriodLength": 1,
    "intervalWindowType": "FIXED",
    "cacheConnectionTimeoutInSeconds": 5,
    "cacheErrorHandlingType": "FAIL",
    "showRateLimitStatisticsInResponseHeader": true,
    "detailList": [
      {
        "targetValue": "VIP",
        "regexExpression": false,
        "messageCountForInterval": 2000,
        "intervalPeriodLength": 1,
        "quotaInterval": "ONE_MINUTE"
      }
    ],
    "policyCondition": {
      "conditionRuleList": [
        {
          "conditionCriteria": "VALUE",
          "firstVariable": {
            "name": "userTypeHeader",
            "type": "HEADER",
            "headerName": "X-User-Type"
          },
          "variableDataType": "STRING",
          "valueComparisonOperator": "EQ",
          "secondValueSource": "VALUE",
          "secondValue": "PREMIUM"
        }
      ]
    }
  }
}
```

#### Request Body Fields

The request body structure is identical to [Add Policy](/api-reference/policies/crud/add-policy). See that documentation for complete field descriptions.

##### operationMetadata

| Field                           | Type    | Required | Default | Description                                                                                          |
| ------------------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------- |
| targetScope                     | string  | Yes      | -       | Policy scope: `ALL` or `ENDPOINT`                                                                    |
| targetEndpoint                  | string  | No\*     | -       | Endpoint path (required if targetScope=ENDPOINT)                                                     |
| targetEndpointHTTPMethod        | string  | No\*     | -       | HTTP method (required if targetScope=ENDPOINT)                                                       |
| targetPipeline                  | string  | Yes      | -       | Pipeline: `REQUEST`, `RESPONSE`, or `ERROR`                                                          |
| deploy                          | boolean | No       | true    | Whether to deploy after updating policy                                                              |
| deployTargetEnvironmentNameList | array   | No       | \[]     | List of environment names to deploy to                                                               |
| order                           | integer | No       | null    | Policy execution order (starts from 1). If null, keeps existing order. If >= list size, moves to end |

**Note:** If `order` is null, the policy keeps its existing position. If `order` is provided, the policy is moved to that position.

### EnumPolicyTargetScope

* `ALL` - Policy applies to all endpoints
* `ENDPOINT` - Policy applies only to specified endpoint

### EnumPolicyTargetPipeline

* `REQUEST` - Executes in request pipeline
* `RESPONSE` - Executes in response pipeline
* `ERROR` - Executes in error pipeline

### EnumHttpRequestMethod

* `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `OPTIONS`, `HEAD`, `TRACE`, `ALL`

##### policy

The policy object structure is identical to Add Policy. All policy fields can be updated.

**Important:** The policy `type` cannot be changed. If you need a different policy type, delete the existing policy and create a new one.

## Response

### Success Response (200 OK)

```json theme={null}
{
  "status": "SUCCESS"
}
```

If `deploy: true` is set in the request, the response includes deployment result:

```json theme={null}
{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": true,
    "responseTime": 1500,
    "detailList": [
      {
        "envName": "production",
        "podName": "pod-123",
        "podIp": "10.0.0.1",
        "success": true,
        "responseTime": 1500
      }
    ]
  }
}
```

#### Response Fields

| Field            | Type   | Description                                                      |
| ---------------- | ------ | ---------------------------------------------------------------- |
| status           | string | Response status: `SUCCESS` or `FAILURE`                          |
| deploymentResult | object | Deployment result (if deploy=true). See Deployment Result Object |

### Deployment Result Object (deploymentResult)

| Field        | Type    | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| success      | boolean | Overall deployment success status              |
| responseTime | integer | Total deployment response time in milliseconds |
| detailList   | array   | List of deployment details per pod/environment |

### Deployment Detail Object (detailList item)

| Field        | Type    | Description                                           |
| ------------ | ------- | ----------------------------------------------------- |
| envName      | string  | Environment name                                      |
| podName      | string  | Pod name where deployment occurred                    |
| podIp        | string  | Pod IP address                                        |
| success      | boolean | Deployment success status for this pod                |
| responseTime | integer | Deployment response time for this pod in milliseconds |

### EnumStatus

* `SUCCESS` - Operation successful
* `FAILURE` - Operation failed

### Error Response (400 Bad Request)

```json theme={null}
{
  "error": "bad_request",
  "error_description": "A policy with name (my-policy) does not exist in API Proxy!"
}
```

#### Common Causes

* Policy name does not exist
* Invalid targetScope (ENDPOINT without targetEndpoint)
* Invalid targetEndpoint (endpoint not found in API Proxy)
* Invalid policy type (cannot change policy type)
* Missing required policy fields
* Invalid condition configuration
* Invalid order value (order \< 1)

### 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!"
}
```

## cURL Example

### Example 1: Update Policy Configuration

```bash theme={null}
curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/throttling-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": true,
      "deployTargetEnvironmentNameList": ["production"],
      "order": 1
    },
    "policy": {
      "type": "policy-api-based-throttling",
      "description": "Updated throttling policy - increased limit",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 200,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED"
    }
  }'
```

### Example 2: Update Policy Order

Move a policy to a different position in the pipeline.

```bash theme={null}
curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/throttling-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": false,
      "order": 3
    },
    "policy": {
      "type": "policy-api-based-throttling",
      "description": "Throttling policy",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 100,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED"
    }
  }'
```

### Example 3: Update Policy Scope

Move a policy from ALL endpoints to a specific endpoint.

```bash theme={null}
curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/throttling-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ENDPOINT",
      "targetEndpoint": "/api/users",
      "targetEndpointHTTPMethod": "GET",
      "targetPipeline": "REQUEST",
      "deploy": false,
      "order": 1
    },
    "policy": {
      "type": "policy-api-based-throttling",
      "description": "Endpoint-specific throttling",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 50,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED"
    }
  }'
```

### Example 4: Update Policy Pipeline

Move a policy from REQUEST pipeline to RESPONSE pipeline.

```bash theme={null}
curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/logging-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "RESPONSE",
      "deploy": false,
      "order": 1
    },
    "policy": {
      "type": "policy-script",
      "description": "Response logging",
      "active": true,
      "scriptLanguage": "GROOVY",
      "scriptBody": "log.info(\"Response: \" + response.statusCode)"
    }
  }'
```

## Permissions

* User must have **`API_MANAGEMENT` + `MANAGE`** permission in the project
* If `deploy: true` is set in the request, user must also have **`API_MANAGEMENT` + `DEPLOY_UNDEPLOY`** permission

## Notes and Warnings

* **Policy Name**: Policy name cannot be changed. Use Delete and Add to rename a policy.
* **Policy Type**: Policy type cannot be changed. Use Delete and Add to change policy type.
* **Order**: If `order` is null, the policy keeps its existing position. If `order` is provided, the policy is moved to that position (1-based indexing).
* **Scope Change**: You can change `targetScope` from ALL to ENDPOINT or vice versa. Ensure the endpoint exists if using ENDPOINT scope.
* **Pipeline Change**: You can change `targetPipeline` (REQUEST, RESPONSE, ERROR). The policy will be moved to the new pipeline.
* **Deployment**: If `deploy: true`, ensure environments exist and user has deployment permissions.
* **Validation**: All policy-specific validations apply. See individual policy documentation for required fields.

## Related Documentation

* [Add Policy](/api-reference/policies/crud/add-policy) - Add a new policy
* [Delete Policy](/api-reference/policies/crud/delete-policy) - Delete a policy
* [List Policies](/api-reference/policies/crud/list-policies) - List all policies
* [Policy API Based Throttling](/api-reference/policies/policies/policy-api-based-throttling) - Example policy documentation