Import API Proxy

Endpoint

POST /apiops/projects/{projectName}/apiProxies/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

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",
  "advisories": [
    {
      "level": "warn",
      "key": "droppedReferences",
      "params": { "names": "my-credential -> organizationId: no matching REGISTERED_ORGANIZATION in this project" }
    }
  ],
  "unresolvedReferences": [
    "droppedReferences: names=my-credential -> organizationId: no matching REGISTERED_ORGANIZATION in this project"
  ]
}

Response Fields

Field	Type	Description
status	string	Response status: `SUCCESS` or `FAILURE`
advisories	array[object]	Machine-readable import report — everything the import could not carry or had to decide on its own (dropped references, objects that need a deploy, secrets that were replaced). Each entry has a stable `key`, a `level` (`info`/`warn`) and raw `params`. Same shape as the generic `/export-import/` endpoints. Empty when nothing needs attention
unresolvedReferences	array[string]	The same report as one human-readable line per advisory (`key: param=value …`). Kept for callers that predate `advisories`

Error Response (400 Bad Request)

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

{
  "status": "FAILURE",
  "resultMessage": "apiProxyExportFile value 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": "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"
}

or, when the package is an MCP gateway (withDependencies=true) that exposes another API Proxy's endpoints as tools — see Import-Time Errors for MCP Gateway Source Proxies:

{
  "status": "FAILURE",
  "resultMessage": "The MCP gateway 'MyMcpGateway' cannot be imported: the API Proxy 'OrdersAPI' behind one of its tools does not exist in the target project and is not in the package. Export the gateway again with its source API Proxies included, map the tool to an existing proxy, or create that proxy here first."
}

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
The package is an MCP gateway whose tool's source API Proxy could not be resolved, was ambiguous, or is missing the pinned endpoint (mcpSourceProxyUnresolved / mcpSourceProxyAmbiguous / mcpToolEndpointMissing) — see Export API Proxy

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

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

Endpoint​

Authentication​

Header​

Request​

Headers​

Path Parameters​

Query Parameters​

Form Data​

Notes​

Response​

Success Response (200 OK)​

Response Fields​

Error Response (400 Bad Request)​

Common Causes​

Error Response (401 Unauthorized)​

cURL Example​

Example 1: Import API Proxy​

Example 2: Import API Proxy with Custom Filename​

Example 3: Import an Encrypted Package​

Example 4: Import a Package with its Dependencies​

Example 5: Import with Environment Mapping​

Notes and Warnings​

Permissions​

Related Documentation​