Update Metadata

Endpoint

PATCH /apiops/projects/{projectName}/apiProxies/{apiProxyName}/settings/metadata/

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

Request Body

Full JSON Body Example - Update All Metadata

{
  "name": "Updated API Name",
  "description": "Updated API description",
  "categoryList": [
    "Payment",
    "E-commerce",
    "Public"
  ],
  "sharingType": "BOTH",
  "deploy": false,
  "deployTargetEnvironmentNameList": []
}

Full JSON Body Example - Update Name Only

{
  "name": "New API Name"
}

Full JSON Body Example - Update Description and Categories

{
  "description": "Updated description for the API",
  "categoryList": [
    "Finance",
    "Banking"
  ]
}

{
  "sharingType": "EXTERNAL"
}

Full JSON Body Example - Update Body Read Behavior

{
  "requestBodyReadBehavior": "READ_IF_POLICY_EXISTS",
  "responseBodyReadBehavior": "ALWAYS_READ"
}

Request Body Fields

Field	Type	Required	Default	Description
name	string	No	-	API Proxy name. Must be unique within the project if provided
description	string	No	-	API Proxy description
categoryList	array[string]	No	-	List of category names for API Proxy organization
sharingType	string	No	-	Sharing type for API Proxy. See EnumSharingType
requestBodyReadBehavior	string	No	-	Request body read behavior. See Body Read Behavior
responseBodyReadBehavior	string	No	-	Response body read behavior. See Body Read Behavior
direction	string	No	-	API contract direction. See EnumContractDirection
disableDirectAccessToGateways	boolean	No	-	Disable direct access to gateways (force access through API Portal)
globalApiProxySettingName	string	No	-	Name of the Global API Proxy Setting to apply (resolved by name)
backendProxyApplyPolicies	boolean	No	-	Apply policies when this proxy acts as a backend proxy
fixSoapApiPortType	boolean	No	-	Fix SOAP API port type naming (only for SOAP proxies)
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)

EnumSharingType (sharingType)

BOTH - Share with both internal and external users
NONE - Do not share (private)
EXTERNAL - Share only with external users
INTERNAL - Share only with internal users

EnumContractDirection

REQUEST_RESPONSE - Standard request/response API
REQUEST_ONLY - Fire-and-forget (request only, no response expected)
RESPONSE_ONLY - Response only (e.g., server push, event stream)

Body Read Behavior (requestBodyReadBehavior / responseBodyReadBehavior)

Controls when the gateway reads the request or response body. This setting can optimize performance by skipping unnecessary body reads.

ALWAYS_READ - Always read the body (default behavior)
READ_IF_POLICY_EXISTS - Read the body only if a policy that needs body access exists
NEVER_READ - Never read the body

Notes

All fields are optional
At least one field must be provided
If name is provided, it must be unique within the project
categoryList can be empty array to clear all categories
description can be set to empty string to clear description
sharingType controls who can access the API Proxy

Response

Success Response (200 OK)

{
  "success": true
}

When deploy=true is specified:

{
  "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	Only present when `deploy=true`
deploymentResult.success	boolean	Overall deployment success status
deploymentResult.deploymentResults	array	Per-environment deployment results

Error Response (400 Bad Request)

{
  "error": "bad_request",
  "error_description": "ApiProxy (name: Updated API Name) is already exist!"
}

Common Causes

Provided name already exists in the project
Invalid sharingType value

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 All Metadata

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/metadata/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated API Name",
    "description": "Updated API description",
    "categoryList": [
      "Payment",
      "E-commerce",
      "Public"
    ],
    "sharingType": "BOTH"
  }'

Example 2: Update Name Only

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/metadata/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New API Name"
  }'

Example 3: Update Description and Categories

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/metadata/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for the API",
    "categoryList": [
      "Finance",
      "Banking"
    ]
  }'

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/metadata/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sharingType": "EXTERNAL"
  }'

Example 5: Update Body Read Behavior

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/metadata/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestBodyReadBehavior": "READ_IF_POLICY_EXISTS",
    "responseBodyReadBehavior": "ALWAYS_READ"
  }'

Example 6: Update Advanced Settings

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/metadata/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "REQUEST_RESPONSE",
    "disableDirectAccessToGateways": true,
    "backendProxyApplyPolicies": false
  }'

Example 7: Assign Global API Proxy Setting

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/metadata/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "globalApiProxySettingName": "My Global Setting"
  }'

Example 8: Clear Categories

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/metadata/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryList": []
  }'

Example 9: Save and Deploy

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/metadata/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated API description",
    "sharingType": "BOTH",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"]
  }'

Notes and Warnings

Name Uniqueness:
- API Proxy names must be unique within the project
- If you try to set a name that already exists, the request will fail
- Name changes are immediate and affect API Proxy identification
Partial Updates:
- You can update any combination of fields
- Fields not provided will remain unchanged
- Empty arrays clear categories
Sharing Type:
- BOTH - API Proxy is visible to both internal and external users
- INTERNAL - API Proxy is visible only to internal users
- EXTERNAL - API Proxy is visible only to external users
- NONE - API Proxy is private (not shared)
Body Read Behavior:
- ALWAYS_READ reads the body for every request (default)
- READ_IF_POLICY_EXISTS optimizes performance by skipping body read when no policy needs it
- NEVER_READ never reads the body, useful for pass-through proxies
- Applies independently to request and response
Categories:
- Categories are used for API Proxy organization and discovery
- Multiple categories can be assigned to a single API Proxy
- Categories are case-sensitive
- Empty array clears all categories
Description:
- Description provides additional information about the API Proxy
- Can be used for documentation and discovery
- Can be set to empty string to clear description
Contract Direction:
- REQUEST_RESPONSE is the standard mode for most APIs
- REQUEST_ONLY is for fire-and-forget scenarios
- RESPONSE_ONLY is for server push or event stream scenarios
Gateway Access:
- When disableDirectAccessToGateways=true, clients must access the API through the API Portal
Global Settings:
- globalApiProxySettingName accepts the setting name (not ID) — the system resolves it internally
- The named setting must exist in the same project
Backend Proxy:
- backendProxyApplyPolicies controls whether policies are applied when this proxy is invoked as a backend by another proxy
SOAP Fix:
- fixSoapApiPortType is only applicable to SOAP API Proxies
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.

Immediate Effect:
- Metadata changes take effect immediately
- Name changes affect API Proxy identification
- Sharing type changes affect API Proxy visibility
API Proxy Discovery:
- Metadata is used for API Proxy discovery and search
- Categories help users find relevant API Proxies
- Description provides context about API Proxy purpose

Get API Proxy - Get API proxy details (includes metadata)
Update API Keys - Update API keys
List API Proxies - List all API Proxies (filtered by metadata)

Endpoint​

Authentication​

Header​

Request​

Headers​

Path Parameters​

Request Body​

Full JSON Body Example - Update All Metadata​

Full JSON Body Example - Update Name Only​

Full JSON Body Example - Update Description and Categories​

Full JSON Body Example - Update Sharing Type​

Full JSON Body Example - Update Body Read Behavior​

Request Body Fields​

EnumSharingType (sharingType)​

EnumContractDirection​

Body Read Behavior (requestBodyReadBehavior / responseBodyReadBehavior)​

Notes​

Response​

Success Response (200 OK)​

Response Fields​

Error Response (400 Bad Request)​

Common Causes​

Error Response (401 Unauthorized)​

Error Response (404 Not Found)​

cURL Example​

Example 1: Update All Metadata​

Example 2: Update Name Only​

Example 3: Update Description and Categories​

Example 4: Update Sharing Type​

Example 5: Update Body Read Behavior​

Example 6: Update Advanced Settings​

Example 7: Assign Global API Proxy Setting​

Example 8: Clear Categories​

Example 9: Save and Deploy​

Notes and Warnings​

Permissions​

Related Documentation​