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

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

​

Authentication

Requires a Personal API Access Token.

​

Header

Authorization: Bearer YOUR_TOKEN

​

Request

​

Headers

Header	Value	Required
Authorization	Bearer	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

{
  "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. 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)

{
  "status": "SUCCESS"
}

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

{
  "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)

{
  "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)

{
  "error": "unauthorized_client",
  "error_description": "Invalid token"
}

​

Error Response (404 Not Found)

{
  "error": "not_found",
  "error_description": "ApiProxy (name: MyAPI) was not found!"
}

​

cURL Example

​

Example 1: Update Policy Configuration

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.

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.

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.

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 - Add a new policy
• Delete Policy - Delete a policy
• List Policies - List all policies
• Policy API Based Throttling - Example policy documentation