Import API Proxy

Endpoint

POST /apiops/projects/{projectName}/apiProxies/import/

Authentication

Requires a Personal API Access Token.

Header

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

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
apiProxyExportFile	file	Yes	ZIP file containing the API Proxy export. Must have .zip extension
environmentMapping	string (JSON)	No	Maps an environment name in the package to an environment name on this installation, e.g. {"UAT":"Production"}. An empty value marks that environment as deliberately not transferred. Without it, same-named environments match and unmatched ones are dropped

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 an API Proxy with the same name exists, a suffix will be added automatically
• 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
• The imported API Proxy always starts undeployed in every environment of the target project; the deployment state stored in the package is not carried over

Response

Success Response (200 OK)

{
  "status": "SUCCESS"
}

Response Fields

Field	Type	Description
status	string	Response status: SUCCESS or FAILURE

Error Response (400 Bad Request)

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

or

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

or

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

or

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

or

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

or

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

or

{
  "status": "FAILURE",
  "resultMessage": "environmentMapping must be a JSON object of \"package environment name\":\"target environment name\" pairs (an empty value means \"do not transfer this environment\"). Received: {not valid json"
}

Common Causes

• Empty projectName
• Empty or missing file
• File is not a ZIP archive
• File does not have .zip extension
• Invalid API Proxy export format
• 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
• environmentMapping was supplied but is not a valid JSON object of environment-name pairs

Error Response (401 Unauthorized)

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

cURL Example

Example 1: Import API Proxy

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 2: Import API Proxy with Custom Filename

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "apiProxyExportFile=@my-api-export.zip"

Example 3: Import an Encrypted Package

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

Example 4: Import a Package with its Dependencies

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/import/?withDependencies=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip"

Example 5: Import with Environment Mapping

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "apiProxyExportFile=@apiProxyExportFile.zip" \
  -F 'environmentMapping={"UAT":"Production"}'

Notes and Warnings

• No Override:

  • This endpoint does not override existing API Proxies
  • If an API Proxy with the same name exists, a suffix will be added automatically
  • Original API Proxy remains unchanged
  • This endpoint never replaces an existing certificate/keystore/key object either, so it does not accept the certEnvironmentMergeMethod / certEnvironmentUncoveredAction parameters at all — they belong to the With Override variant

• Environment Mapping:

  • environmentMapping maps an environment name in the package to an environment name on this installation, e.g. {"UAT":"Production"}
  • An empty value ({"UAT":""}) marks that environment as deliberately not transferred
  • Without it, same-named environments match and unmatched ones are dropped — today's default behavior
  • Applies whether or not withDependencies is used

• Automatic Naming:

  • Imported API Proxy name may be modified if a conflict exists
  • Relative paths may also be modified to prevent conflicts
  • Check the imported API Proxy name after import

• 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

• 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

• Deployment Status:

  • Imported API Proxy is not deployed by default
  • Deployment status from export is preserved
  • You may need to deploy the imported API Proxy manually

• 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)

Permissions

• User must have API_MANAGEMENT + EXPORT_IMPORT permission in the project

• Alternatively, user can have project admin role

• 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

Related Documentation

• Export API Proxy - Export API Proxy to ZIP file
• Import API Proxy (With Override) - Import API Proxy with override option
• List API Proxies - List all API Proxies in project