Add Policy

Adds a new policy to an API Proxy. The policy can be added to the request, response, or error pipeline, and can apply to all endpoints or a specific endpoint.

​

Endpoint

POST /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 be unique within the API Proxy)

​

Request Body

​

Full JSON Body Example

{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-api-based-throttling",
    "description": "API throttling policy - 100 requests per minute",
    "active": true,
    "targetVariableForIdentity": {
      "type": "HEADER",
      "headerName": "X-API-Key"
    },
    "messageCountForInterval": 100,
    "throttlingInterval": "ONE_MINUTE",
    "intervalPeriodLength": 1,
    "intervalWindowType": "FIXED",
    "cacheConnectionTimeoutInSeconds": 3,
    "cacheErrorHandlingType": "FAIL",
    "showRateLimitStatisticsInResponseHeader": true,
    "detailList": [
      {
        "targetValue": "VIP",
        "regexExpression": false,
        "messageCountForInterval": 1000,
        "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

Policy Operation Metadata

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 adding policy
deployTargetEnvironmentNameList	array	No	[]	List of environment names to deploy to
order	integer	No	null	Policy execution order (starts from 1). If null or >= list size, policy is added at the end

​

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 - GET method
• POST - POST method
• PUT - PUT method
• DELETE - DELETE method
• PATCH - PATCH method
• OPTIONS - OPTIONS method
• HEAD - HEAD method
• TRACE - TRACE method
• ALL - All methods

Note: When targetScope is ENDPOINT, both targetEndpoint and targetEndpointHTTPMethod are required.

policy

The policy object structure varies by policy type. All policies share common base fields:

Common Policy Fields

Field	Type	Required	Default	Description
type	string	Yes	-	Policy type (discriminator field)
description	string	No	-	Policy description
active	boolean	No	true	Whether policy is active
policyCondition	object	No	-	Policy condition configuration (see PolicyCondition below)
errorMessageList	array	No	-	Custom error messages (if not provided, standard messages are used)

Note: The name field is not included in the request body. The policy name is taken from the path parameter {policyName}.

Policy Types

Each policy type has its own specific fields. See individual policy documentation pages for details:

• API Based Throttling
• Blocked IP List
• Allowed IP List
• Authentication Basic
• … (see Policies Index for complete list)

Policy Condition (PolicyConditionDTO)

Field	Type	Required	Default	Description
conditionRuleList	array	No	[]	List of condition rules. If empty, default AND condition is used

Note: If conditionRuleList is empty or not provided, a default AND condition is created.

conditionRuleList Item (ConditionRuleDTO)

Field	Type	Required	Default	Description
conditionRuleList	array	No	[]	Nested condition rules (for complex conditions)
conditionCriteria	string	Yes	-	Condition criteria: VALUE, NOT, AND, or OR
firstVariable	object	Yes	-	First variable for comparison (see VariableDTO below)
variableDataType	string	Yes	-	Variable data type: STRING, NUMBER, DATE, BOOLEAN
dateFormat	string	No	-	Date format for date comparisons (required if variableDataType=DATE)
valueComparisonOperator	string	Yes	-	Comparison operator (see EnumConditionValueComparisonOperator below)
secondValueSource	string	Yes	-	Second value source: VALUE or VARIABLE
secondValue	string	No*	-	Second value for comparison (required if secondValueSource=VALUE)
secondVariable	object	No*	-	Second variable for comparison (required if secondValueSource=VARIABLE)

​

EnumConditionCriteria

• VALUE - Value comparison
• NOT - Negation
• AND - Logical AND
• OR - Logical OR

​

EnumConditionVariableDataType

• STRING - String type
• NUMERIC - Numeric type
• DATE - Date type

​

EnumConditionValueComparisonOperator

• LT - Less than
• LE - Less than or equal to
• GT - Greater than
• GE - Greater than or equal to
• EQ - Equal to
• NE - Not equal to
• EQ_IGNORE_CASE - Equal to, case insensitive (string only)
• NE_IGNORE_CASE - Not equal to, case insensitive (string only)
• STARTS_WITH - Starts with (string only)
• NOT_STARTS_WITH - Does not start with (string only)
• STARTS_WITH_IGNORE_CASE - Starts with, case insensitive (string only)
• NOT_STARTS_WITH_IGNORE_CASE - Does not start with, case insensitive (string only)
• ENDS_WITH - Ends with (string only)
• NOT_ENDS_WITH - Does not end with (string only)
• ENDS_WITH_IGNORE_CASE - Ends with, case insensitive (string only)
• NOT_ENDS_WITH_IGNORE_CASE - Does not end with, case insensitive (string only)
• CONTAINS - Contains (string only)
• NOT_CONTAINS - Does not contain (string only)
• CONTAINS_IGNORE_CASE - Contains, case insensitive (string only)
• NOT_CONTAINS_IGNORE_CASE - Does not contain, case insensitive (string only)
• IS_EXISTS - Variable exists (regardless of value)
• IS_NOT_EXISTS - Variable does not exist
• IS_NOT_EMPTY - Variable exists and is not empty
• IS_EMPTY - Variable does not exist or is empty
• EXISTS_AND_EMPTY - Variable exists but is empty
• IN - Value is in list
• NOT_IN - Value is not in list
• IN_IGNORE_CASE - Value is in list, case insensitive (string only)
• NOT_IN_IGNORE_CASE - Value is not in list, case insensitive (string only)

​

EnumConditionValueSource

• VALUE - Compare with a constant value
• VARIABLE - Compare with another variable

firstVariable / secondVariable (VariableDTO)

Field	Type	Required	Default	Description
id	string	No	-	Variable ID (if referencing existing variable)
projectId	string	No	-	Project ID (if referencing existing variable)
name	string	No*	-	Variable name (required if id not provided)
description	string	No	-	Variable description
type	string	Yes	-	Variable type: HEADER, PARAMETER, BODY, CONTEXT_VALUES, CUSTOM
headerName	string	No*	-	Header name (required if type=HEADER)
paramType	string	No*	-	Parameter type: QUERY, PATH, FORM (required if type=PARAMETER)
paramName	string	No*	-	Parameter name (required if type=PARAMETER)
paramPath	string	No	-	Parameter path
formName	string	No	-	Form name (for form parameters)
xpathValue	string	No*	-	XPath value (required if type=BODY and content is XML)
jsonPathValue	string	No*	-	JSONPath value (required if type=BODY and content is JSON)
messageContentType	string	No*	-	Message content type: JSON, XML, FORM (required if type=BODY)
contextValue	string	No*	-	Context value (required if type=CONTEXT_VALUES)
zoneId	string	No	-	Zone ID (for date context values)
initWithScript	boolean	No	false	Initialize with script
scriptLanguage	string	No	-	Script language: GROOVY, JAVASCRIPT (required if initWithScript=true)
scriptBody	string	No	-	Script body (required if initWithScript=true)

​

EnumVariableType

• HEADER - HTTP header
• PARAMETER - Query/path/form parameter
• BODY - Request/response body
• CONTEXT_VALUES - Context values (e.g., current time, IP address)
• CUSTOM - Custom variable (script-based)

​

EnumVariableParameterType

• QUERY - Query parameter
• PATH - Path parameter
• FORM - Form parameter

​

EnumMessageContentType

• JSON - JSON content
• XML - XML content
• FORM - Form content

​

EnumVariableContextValue

• CURRENT_TIME - Current timestamp
• CURRENT_DATE - Current date
• CLIENT_IP - Client IP address
• CLIENT_PORT - Client port
• SERVER_IP - Server IP address
• SERVER_PORT - Server port
• REQUEST_METHOD - HTTP request method
• REQUEST_URI - Request URI
• REQUEST_PATH - Request path
• REQUEST_QUERY_STRING - Query string
• REQUEST_PROTOCOL - Request protocol
• REQUEST_HOST - Request host
• REQUEST_SCHEME - Request scheme
• RESPONSE_STATUS_CODE - Response status code
• RESPONSE_STATUS_TEXT - Response status text
• API_PROXY_NAME - API Proxy name
• API_PROXY_ID - API Proxy ID
• ENDPOINT_NAME - Endpoint name
• ENDPOINT_ID - Endpoint ID
• ENVIRONMENT_NAME - Environment name
• ENVIRONMENT_ID - Environment ID
• PROJECT_NAME - Project name
• PROJECT_ID - Project ID
• USER_NAME - User name
• USER_ID - User ID
• ORGANIZATION_NAME - Organization name
• ORGANIZATION_ID - Organization ID
• ZONE_ID - Zone ID
• TIMEZONE_ID - Timezone ID

​

EnumScriptType

• GROOVY - Groovy script
• JAVASCRIPT - JavaScript script

​

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 same name (my-policy) is already exist in API Proxy!"
}

​

Common Causes

• Policy name already exists
• Invalid targetScope (ENDPOINT without targetEndpoint)
• Invalid targetEndpoint (endpoint not found in API Proxy)
• Invalid policy type
• Missing required policy fields
• Invalid condition configuration

​

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: Add Policy to All Endpoints

curl -X POST \
  "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": "Throttling policy",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 100,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED"
    }
  }'

​

Example 2: Add Policy to Specific Endpoint

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/endpoint-throttling/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ENDPOINT",
      "targetEndpoint": "/api/users",
      "targetEndpointHTTPMethod": "GET",
      "targetPipeline": "REQUEST",
      "deploy": false,
      "order": 2
    },
    "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 3: Add Policy with Condition

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/conditional-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": false,
      "order": 1
    },
    "policy": {
      "type": "policy-black-ip",
      "description": "Block IPs for VIP users",
      "active": true,
      "ipList": ["192.168.1.100"],
      "policyCondition": {
        "conditionRuleList": [
          {
            "conditionCriteria": "VALUE",
            "firstVariable": {
              "name": "userTypeHeader",
              "type": "HEADER",
              "headerName": "X-User-Type"
            },
            "variableDataType": "STRING",
            "valueComparisonOperator": "EQ",
            "secondValueSource": "VALUE",
            "secondValue": "PREMIUM"
          }
        ]
      }
    }
  }'

​

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 is taken from the path parameter, not from the request body. The name field in PolicyDTO is ignored (marked with @JsonIgnore).
• Unique Names: Policy names must be unique within the API Proxy
• Order: Order starts from 1. If order is null or >= current policy list size, policy is added at the end
• Deployment: If deploy: true, ensure environments exist and user has deployment permissions
• Conditions: If policyCondition is not provided, a default AND condition is created
• Error Messages: If errorMessageList is not provided, standard error messages are used
• Endpoint Scope: When using targetScope: ENDPOINT, ensure the endpoint exists in the API Proxy
• Variable References: Variables can be referenced by id (if existing) or defined inline

​

Related Documentation

• List Policies - List all policies
• Update Policy - Update an existing policy
• Delete Policy - Delete a policy
• Policy API Based Throttling - Example policy documentation