Add Policy

Endpoint

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

Authentication

Requires a Personal API Access Token.

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 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). See Error Messages

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

Error Messages (errorMessageList)

Optional list of custom error message objects. When omitted, the platform assigns standard policy error messages for the policy type. Structure matches the product error message model (HTTP status, fault code, message template). See individual policy pages for type-specific examples.

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	No*	-	Second value source: `VALUE` or `VARIABLE`. Required, except when `valueComparisonOperator` is `IS_EMPTY`, `IS_NOT_EMPTY`, `EXISTS_AND_EMPTY`, `IS_EXISTS` or `IS_NOT_EXISTS`
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
ALL_BODY - Whole body as raw content

EnumVariableContextValue

REQUEST_REMOTE_ADDRESS - Client IP address
REQUEST_XFORWARDED_FOR - X-Forwarded-For header value
REQUEST_REQUEST_URI - Request URI
REQUEST_PATH_INFO - Request path
REQUEST_HTTP_METHOD - HTTP method

The full list is on Variable Definition.

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)

{
  "status": "FAILURE",
  "resultMessage": "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)

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

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
On an AI, MCP or A2A proxy, AI_DEVELOPMENT + MANAGE is accepted as well as API_MANAGEMENT + MANAGE. Other proxy types need API_MANAGEMENT + MANAGE.
If deploy: true is set in the request, user must also have DEPLOY_UNDEPLOY permission: in AI_DEVELOPMENT for an AI, MCP or A2A proxy, and in API_MANAGEMENT for every other proxy type. A user with only API_MANAGEMENT + DEPLOY_UNDEPLOY can no longer deploy an AI, MCP or A2A proxy through this endpoint.

Notes and Warnings

Policy Name: Policy name is taken from the path parameter, not from the request body. The name field is read-only: List Policies returns it, and a name in the request body is ignored.
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
Save Checks: The policy gets the same save checks as its policy screen in the Manager. A rejected policy returns 400 Bad Request with a message that names the policy.
AI, MCP and A2A Proxies: ai-mcp-call-llm, ai-mcp-call-fixed, ai-a2a-call-llm and ai-a2a-call-fixed bodies carry identityAcl and tokenForwardSettings. See MCP Tool Call and A2A Agent Call.

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

Endpoint​

Authentication​

Header​

Request​

Headers​

Path Parameters​

Request Body​

Full JSON Body Example​

Request Body Fields​

Policy Operation Metadata​

EnumPolicyTargetScope​

EnumPolicyTargetPipeline​

EnumHttpRequestMethod​

policy​

Common Policy Fields​

Error Messages (errorMessageList)​

Policy Types​

Policy Condition (PolicyConditionDTO)​

conditionRuleList Item (ConditionRuleDTO)​

EnumConditionCriteria​

EnumConditionVariableDataType​

EnumConditionValueComparisonOperator​

EnumConditionValueSource​

firstVariable / secondVariable (VariableDTO)​

EnumVariableType​

EnumVariableParameterType​

EnumMessageContentType​

EnumVariableContextValue​

EnumScriptType​

Response​

Success Response (200 OK)​

Response Fields​

Deployment Result Object (deploymentResult)​

Deployment Detail Object (detailList item)​

EnumStatus​

Error Response (400 Bad Request)​

Common Causes​

Error Response (401 Unauthorized)​

cURL Example​

Example 1: Add Policy to All Endpoints​

Example 2: Add Policy to Specific Endpoint​

Example 3: Add Policy with Condition​

Permissions​

Notes and Warnings​

Related Documentation​