Import API Proxy (With Override)

Endpoint

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/import/

Authentication

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	multipart/form-data	Yes
X-Apinizer-Package-Passphrase	Base64 of the UTF-8 passphrase	Only if the uploaded package is encrypted

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name where the API Proxy will be imported
apiProxyName	string	Yes	API Proxy name (will override existing API Proxy with this name)

Query Parameters

Parameter	Type	Required	Default	Description
withDependencies	boolean	No	false	When `true`, the dependencies carried in the package (if any) are resolved against the target project: an object with the SAME NAME in the target is reused, otherwise the dependency is imported as new. When `false` (default), the package is imported as-is (previous behavior). Has no effect if the package carries no dependencies

Form Data

Parameter	Type	Required	Description
metadata	string (JSON)	Yes	Metadata for API Proxy creation/update. See Metadata Object
apiProxyExportFile	file	Yes	ZIP file containing the API Proxy export. Must have `.zip` extension
certEnvironmentMergeMethod	string	No	When the package carries certificate/keystore/key objects (e.g. backend TLS material): how their environment-scoped data merges onto the existing objects. `MATCH_BY_NAME` (default) writes only the environments named in the package, `OVERWRITE_ALL` writes the package's first entry onto every target environment
certEnvironmentUncoveredAction	string	No	For the same certificate/keystore/key objects: what happens to a target environment the package does not cover. `FILL_FROM_PACKAGE` writes the package's data onto it, `REMOVE_FROM_TARGET` drops it from the object. If such an uncovered environment actually exists and this is not supplied, the import is rejected with 400 rather than silently leaving it with stale material

Metadata Object

The metadata parameter is a JSON string containing optional configuration for the import process.

Full JSON Metadata Example - Basic Import

{
  "deploy": false,
  "deployTargetEnvironmentNameList": null,
  "routing": null,
  "maintenanceMode": null
}

Full JSON Metadata Example - Import with Deployment

{
  "deploy": true,
  "deployTargetEnvironmentNameList": ["production", "staging"],
  "routing": null,
  "maintenanceMode": null
}

Full JSON Metadata Example - Import with Routing

{
  "deploy": false,
  "deployTargetEnvironmentNameList": null,
  "routing": {
    "algorithm": "ROUND_ROBIN",
    "addressList": [
      {
        "address": "https://backend1.example.com",
        "weight": 1,
        "soapType": null
      },
      {
        "address": "https://backend2.example.com",
        "weight": 1,
        "soapType": null
      }
    ]
  },
  "maintenanceMode": false
}

Metadata Object Fields

Field	Type	Required	Default	Description
deploy	boolean	No	false	Deploy API Proxy after import
deployTargetEnvironmentNameList	array[string]	No	null	List of environment names to deploy to (if deploy=true)
routing	object	No	null	Routing configuration. See Routing Object
maintenanceMode	boolean	No	null	Enable/disable maintenance mode

Routing Object

Field	Type	Required	Description
algorithm	string	No	Routing algorithm. See EnumRoutingAlgorithm
addressList	array[object]	No	List of routing addresses. See Routing Address Object

EnumRoutingAlgorithm (routing.algorithm)

ROUND_ROBIN - Round-robin load balancing
WEIGHTED_ROUND_ROBIN - Weighted round-robin load balancing
LEAST_CONNECTIONS - Least connections load balancing
RANDOM - Random selection
IP_HASH - IP hash-based routing
URL_HASH - URL hash-based routing

Routing Address Object

Field	Type	Required	Description
address	string	Yes	Backend address URL
weight	integer	No	Weight for weighted algorithms (default: 1)
soapType	string	No	SOAP version for SOAP APIs. See EnumSoapApiPortType

EnumSoapApiPortType (soapType)

SOAP11 - SOAP 1.1
SOAP12 - SOAP 1.2

Notes

File must be a valid ZIP archive
File must end with .zip extension (case-insensitive)
ZIP file must contain a valid API Proxy export JSON file
If deploy=true, requires API_MANAGEMENT + DEPLOY_UNDEPLOY permission
Every name in deployTargetEnvironmentNameList is validated before the package is imported. If a name does not exist (or is not accessible to the user), the request fails with 400 Bad Request and nothing is imported
When an existing API Proxy is overridden, its current deployment state is preserved: environments it is already deployed to stay deployed and are flagged as requiring a redeploy. The deployment state stored in the package is never carried over to the target installation
Routing configuration is optional and can be set later
Maintenance mode can be enabled/disabled during import

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": true,
    "message": "Deployment completed successfully",
    "environmentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployed successfully"
      }
    ]
  }
}

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

Field	Type	Description
success	boolean	Overall deployment success status
message	string	Deployment message
environmentResults	array[object]	Results per environment

Environment Result Object

Field	Type	Description
environmentName	string	Environment name
success	boolean	Deployment success status for this environment
message	string	Deployment message for this environment

Success Response (200 OK) - Without Deployment

{
  "status": "SUCCESS"
}

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "projectName value can not be empty!"
}

{
  "status": "FAILURE",
  "resultMessage": "apiProxyName value can not be empty!"
}

{
  "status": "FAILURE",
  "resultMessage": "apiProxyExportFile parameter can not be empty!"
}

{
  "status": "FAILURE",
  "resultMessage": "apiProxyExportFile parameter must be in zip file format and must end with zip extension!"
}

{
  "status": "FAILURE",
  "resultMessage": "Package is encrypted; a passphrase is required."
}

{
  "status": "FAILURE",
  "resultMessage": "Package could not be decrypted with the given passphrase."
}

{
  "status": "FAILURE",
  "resultMessage": "Encrypted package could not be read."
}

{
  "status": "FAILURE",
  "resultMessage": "Replace Existing of CERTIFICATE 'backend-tls-cert' cannot proceed: the package carries no data for the target environment(s) UAT, so they would keep their old material while the rest is replaced. Send the certEnvironmentUncoveredAction parameter with either FILL_FROM_PACKAGE (write the package's data onto them) or REMOVE_FROM_TARGET (drop them from the object) and import again."
}

Common Causes

Empty projectName or apiProxyName
Empty or missing file
File is not a ZIP archive
File does not have .zip extension
Invalid API Proxy export format
Invalid metadata JSON format
Deployment failed (if deploy=true)
The uploaded package is encrypted but the X-Apinizer-Package-Passphrase header was not provided
The supplied passphrase does not open the package
The file is not a package this version can read — corrupted or unsupported format
The package carries a certificate/keystore/key object whose target has an environment the package does not cover, and certEnvironmentUncoveredAction was not supplied

Error Response (401 Unauthorized)

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

cURL Example

Example 1: Basic Import (No Override)

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "metadata={\"deploy\":false}" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 2: Import with Deployment

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "metadata={\"deploy\":true,\"deployTargetEnvironmentNameList\":[\"production\",\"staging\"]}" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 3: Import with Routing Configuration

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'metadata={"deploy":false,"routing":{"algorithm":"ROUND_ROBIN","addressList":[{"address":"https://backend1.example.com","weight":1},{"address":"https://backend2.example.com","weight":1}]}}' \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 4: Import with Full Configuration

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'metadata={"deploy":true,"deployTargetEnvironmentNameList":["production"],"routing":{"algorithm":"WEIGHTED_ROUND_ROBIN","addressList":[{"address":"https://backend1.example.com","weight":3},{"address":"https://backend2.example.com","weight":1}]},"maintenanceMode":false}' \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 5: Import an Encrypted Package

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Apinizer-Package-Passphrase: $(printf '%s' 'my-passphrase' | base64)" \
  -F "metadata={\"deploy\":false}" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 6: Import a Package with its Dependencies

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/?withDependencies=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "metadata={\"deploy\":false}" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 7: Replace Existing with Uncovered-Environment Handling

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "metadata={\"deploy\":false}" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip" \
  -F "certEnvironmentMergeMethod=MATCH_BY_NAME" \
  -F "certEnvironmentUncoveredAction=FILL_FROM_PACKAGE"

Notes and Warnings

Override Behavior:
- This endpoint overrides existing API Proxies with the same name
- Existing API Proxy configuration will be replaced
- Original API Proxy data is lost after override
- This endpoint also accepts an environmentMapping part — a malformed value is still rejected with 400, but a valid one has no effect since override is always true here (the mapping only applies to Import as New — the "Without Override" variant of this endpoint)
Certificate/Key Environment Merge:
- When the package carries certificate/keystore/key objects (e.g. backend TLS material) that already exist by name in the target project, certEnvironmentMergeMethod decides how their environment-scoped data merges onto the existing object: MATCH_BY_NAME (default) only touches environments the package names, OVERWRITE_ALL writes the package's first entry onto every target environment
- If a target environment is left uncovered by the package under MATCH_BY_NAME, the import used to silently keep that environment's old material — a partial transfer with no warning. It is now blocked with a 400 unless certEnvironmentUncoveredAction says what to do with it (FILL_FROM_PACKAGE or REMOVE_FROM_TARGET)
- Has no effect when the package carries no certificate/keystore/key objects
Deployment:
- If deploy=true, API Proxy will be deployed after import
- Deployment targets must be specified in deployTargetEnvironmentNameList
- Deployment results are returned in the response
Routing Configuration:
- Routing can be configured during import
- Routing algorithm and addresses can be set
- Routing configuration is optional
Maintenance Mode:
- Maintenance mode can be enabled/disabled during import
- Useful for importing API Proxies in maintenance state
File Format:
- File must be a valid ZIP archive
- File must end with .zip extension (case-insensitive)
- ZIP file must contain valid API Proxy export JSON
Encrypted Packages:
- Whether the uploaded package is encrypted is detected automatically
- If it is encrypted, the same passphrase used during export must be supplied in the X-Apinizer-Package-Passphrase header
- The header is ignored for plain (unencrypted) packages
- A package cannot be opened with an incorrect passphrase
Metadata Format:
- Metadata must be valid JSON
- Metadata is passed as a form field (string)
- All metadata fields are optional
Project Validation:
- Project must exist
- User must have access to the project
- User must have API_MANAGEMENT + EXPORT_IMPORT permission
Import Content:
- Import includes all API Proxy configurations
- Includes all associated policies
- Includes routing, cache, CORS, and other settings
Dependency Resolution (withDependencies):
- When omitted or false, the package is imported as-is (previous, default behavior)
- When true and the package carries dependencies (exported with withDependencies=true), each dependency is matched against an existing object of the SAME NAME in the target project, or imported as a new object if none exists
- Has no effect on a package that carries no dependencies (every package produced before withDependencies existed)
File Size:
- Large export files may take longer to import
- Ensure sufficient network bandwidth and server resources
Validation:
- Import validates API Proxy structure
- Invalid configurations may cause import to fail
- Check error messages for validation issues
Deployment Results:
- Deployment results are included in the response
- Check deploymentResult for deployment status
- Each environment deployment result is included separately

Permissions

User must have API_MANAGEMENT + EXPORT_IMPORT permission in the project
Alternatively, user can have project admin role
If deploy=true is set, user must also have API_MANAGEMENT + DEPLOY_UNDEPLOY permission

Export API Proxy - Export API Proxy to ZIP file
Import API Proxy - Import API Proxy without override
Deploy API Proxy - Deploy API Proxy to environments
Update Routing Addresses - Update routing configuration

Endpoint​

Authentication​

Header​

Request​

Headers​

Path Parameters​

Query Parameters​

Form Data​

Metadata Object​

Full JSON Metadata Example - Basic Import​

Full JSON Metadata Example - Import with Deployment​

Full JSON Metadata Example - Import with Routing​

Metadata Object Fields​

Routing Object​

EnumRoutingAlgorithm (routing.algorithm)​

Routing Address Object​

EnumSoapApiPortType (soapType)​

Notes​

Response​

Success Response (200 OK)​

Response Fields​

Deployment Result Object​

Environment Result Object​

Success Response (200 OK) - Without Deployment​

Error Response (400 Bad Request)​

Common Causes​

Error Response (401 Unauthorized)​

cURL Example​

Example 1: Basic Import (No Override)​

Example 2: Import with Deployment​

Example 3: Import with Routing Configuration​

Example 4: Import with Full Configuration​

Example 5: Import an Encrypted Package​

Example 6: Import a Package with its Dependencies​

Example 7: Replace Existing with Uncovered-Environment Handling​

Notes and Warnings​

Permissions​

Related Documentation​

Endpoint

Authentication

Header

Request

Headers

Path Parameters

Query Parameters

Form Data

Metadata Object

Full JSON Metadata Example - Basic Import

Full JSON Metadata Example - Import with Deployment

Full JSON Metadata Example - Import with Routing

Metadata Object Fields

Routing Object

EnumRoutingAlgorithm (routing.algorithm)

Routing Address Object

EnumSoapApiPortType (soapType)

Notes

Response

Success Response (200 OK)

Response Fields

Deployment Result Object

Environment Result Object

Success Response (200 OK) - Without Deployment

Error Response (400 Bad Request)

Common Causes

Error Response (401 Unauthorized)

cURL Example

Example 1: Basic Import (No Override)

Example 2: Import with Deployment

Example 3: Import with Routing Configuration

Example 4: Import with Full Configuration

Example 5: Import an Encrypted Package

Example 6: Import a Package with its Dependencies

Example 7: Replace Existing with Uncovered-Environment Handling

Notes and Warnings

Permissions

Related Documentation