Ana içeriğe geç

Export API Proxy

Endpoint​

GET /apiops/projects/{projectName}/apiProxies/{apiProxyName}/export/

Authentication​

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Request​

Headers​

HeaderValueRequired
AuthorizationBearer {token}Yes
X-Apinizer-Package-PassphraseBase64 of the UTF-8 passphraseOnly when encrypt=true

Path Parameters​

ParameterTypeRequiredDescription
projectNamestringYesProject name
apiProxyNamestringYesAPI Proxy name

Query Parameters​

ParameterTypeRequiredDefaultDescription
encryptbooleanNofalseWhen true, encrypts the entire export package — including object names — with the passphrase supplied in the X-Apinizer-Package-Passphrase header
withDependenciesbooleanNofalseWhen true, the package also includes every object the proxy references (global policies, policy groups, certificates, credentials, connections, LLM providers, environment variables, etc.), which the import binds to same-named objects in the target project. When false (default), only the proxy itself is exported (previous behavior)
includeReferencedProxiesbooleanNotrueOnly meaningful together with withDependencies=true. For an MCP gateway that exposes another API Proxy's endpoints as tools: when true (default), those source API Proxies are packaged with the gateway, together with their own dependencies, so the import can rebind the gateway's tools on its own. When false, the source proxies are left out of the package, and the import instead binds each tool to the proxy of the same name and API type already in the target project — the shape a pipeline that promotes its API Proxies separately wants, so each proxy travels exactly once. Has no effect on a proxy that isn't an MCP gateway, or when withDependencies=false

Response​

Success Response (200 OK)​

The response is a ZIP file containing the API Proxy export.

Headers​

  • Content-Type: application/octet-stream
  • Content-Disposition: attachment; filename="<apiProxyName>.zip"

Response Body​

  • Binary ZIP file containing:
    • API Proxy JSON definition file
    • All associated policies
    • All configurations and settings

ZIP File Contents​

  • {apiProxyName}.json - Complete API Proxy definition in JSON format
  • Contains all endpoints, policies, settings, routing configurations, etc.

Error Response (400 Bad Request)​

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

or

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

or

{
  "status": "FAILURE",
  "resultMessage": "ApiProxy (name: MyAPI) was not found!"
}

or

{
  "status": "FAILURE",
  "resultMessage": "Package encryption requested but no passphrase was supplied."
}

or

{
  "status": "FAILURE",
  "resultMessage": "Export package could not be encrypted."
}

Common Causes​

  • Empty projectName or apiProxyName
  • API Proxy does not exist in the project
  • Project does not exist or user does not have access
  • encrypt=true was requested but the X-Apinizer-Package-Passphrase header was not provided
  • The package could not be encrypted with the supplied passphrase

Error Response (401 Unauthorized)​

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

cURL Example​

Example 1: Export API Proxy​

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/export/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output apiProxyExportFile.zip

Example 2: Export API Proxy with Custom Filename​

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/export/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output my-api-export.zip

Example 3: Export an Encrypted API Proxy Package​

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/export/?encrypt=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Apinizer-Package-Passphrase: $(printf '%s' 'my-passphrase' | base64)" \
  --output apiProxyExportFile.zip

Example 4: Export an API Proxy with its Dependencies​

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/export/?withDependencies=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output apiProxyExportFile.zip

Example 5: Export an MCP Gateway Without Its Source Proxies​

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyMcpGateway/export/?withDependencies=true&includeReferencedProxies=false" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output myMcpGateway.zip

Notes and Warnings​

  • Export Format:

    • Exported file is a ZIP archive
    • Contains JSON file with complete API Proxy definition
    • Includes all policies, endpoints, settings, and configurations

  • File Naming:

    • The download is named after the API Proxy, for example MyAPI.zip
    • The name is sanitized, so a proxy whose name contains a slash or another reserved character still produces a valid file name
    • You can rename the downloaded file as needed

  • Complete Export:

    • Export includes all API Proxy configurations
    • Includes all associated policies
    • Includes routing, cache, CORS, and other settings

Permissions​

  • User must have API_MANAGEMENT + EXPORT_IMPORT permission in the project

  • Alternatively, user can have project admin role

  • File Size:

    • Export file size depends on API Proxy complexity
    • Large API Proxies with many policies may result in larger files

  • Import Compatibility:

    • Exported files can be imported using Import endpoints
    • Compatible with Import without Override and Import with Override endpoints

  • Security:

    • By default, export files are unencrypted and contain sensitive configuration data
    • Set encrypt=true with a passphrase to encrypt the entire package
    • Store exported files securely
    • Do not share exported files publicly
    • Share the passphrase through a channel separate from the exported file

  • Package Encryption:

    • Encryption is optional and fully backward compatible — when encrypt is omitted or false, the package is produced as a plain ZIP file, byte-compatible with earlier Apinizer versions
    • When encrypt=true, the entire package — including object names — is encrypted with the supplied passphrase, so nothing about its contents can be observed from the outside
    • The encryption key is derived from the passphrase; the passphrase itself is never written into the package
    • The passphrase is never stored and cannot be recovered — if it is lost, the encrypted package can no longer be opened
    • The same passphrase must be supplied when importing the encrypted package

  • API Proxy State:

    • Export includes current state of API Proxy
    • Includes deployed and undeployed configurations
    • Deployment status is preserved in export

  • Dependency Bundling (withDependencies):

    • When omitted or false, only the proxy itself is exported (default, previous behavior)
    • When true, every object the proxy references — global policies, policy groups, certificates, credentials, connections, LLM providers, environment variables, and more — is bundled into the same package
    • On import, the target project's withDependencies=true resolves bundled objects against same-named objects already in the target project
    • Has no effect on the proxy itself; it only controls whether referenced objects are packaged alongside it

  • MCP Gateway Source Proxy Bundling (includeReferencedProxies):

    • Only applies to an MCP gateway proxy (type=MCP) exported with withDependencies=true; ignored otherwise
    • true (default): each API Proxy the gateway exposes as a tool travels inside the same package, together with its own dependencies
    • false: those source proxies are left out; on import, each tool is instead bound to the API Proxy of the same name and API type already in the target project — see Import-Time Errors for MCP Gateway Source Proxies for what happens when that resolution fails
    • Choose false when a pipeline already promotes its API Proxies through their own export/import step, so a proxy used as an MCP tool doesn't travel a second time bundled inside the gateway's package

Import-Time Errors for MCP Gateway Source Proxies​

These errors surface on the import endpoints (Import API Proxy, Import API Proxy (With Override)) when the uploaded package is an MCP gateway exported with withDependencies=true, and are only relevant because of this endpoint's includeReferencedProxies parameter — they are documented here, next to the parameter that controls whether the source proxy travels in the package at all. All three are checked, and refused, before anything is written to the target project.

Source Proxy Not Found (mcpSourceProxyUnresolved)​

The API Proxy behind one of the gateway's tools was not packaged (includeReferencedProxies=false at export) and no proxy of the same name and API type exists in the target project.

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/import/?withDependencies=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "apiProxyExportFile=@myMcpGateway.zip"
{
  "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."
}

Fix: export again with includeReferencedProxies=true (or leave it at its default), map the tool to an existing proxy on the wizard's mapping step, or create the proxy in the target project first.

Source Proxy Ambiguous (mcpSourceProxyAmbiguous)​

More than one API Proxy of the same name and the same API type already exists in the target project, so name-based resolution cannot pick one.

{
  "status": "FAILURE",
  "resultMessage": "The MCP gateway 'MyMcpGateway' cannot be imported: more than one API Proxy named 'OrdersAPI' of the same API type exists in the target project, so the proxy its tool should call cannot be determined. Rename the duplicates, or map the tool to the intended proxy, before importing."
}

Fix: rename the duplicate proxies in the target project, or export with includeReferencedProxies=true so the intended proxy travels with the package instead of being resolved by name.

MCP Tool Endpoint Missing (mcpToolEndpointMissing)​

A tool is pinned to one specific operation (HTTP method + path) of its source proxy, and the proxy the import resolved does not have that operation.

{
  "status": "FAILURE",
  "resultMessage": "The MCP gateway 'MyMcpGateway' cannot be imported: its tool 'GET /orders' is pinned to the endpoint GET /orders of the API Proxy 'OrdersAPI', and that endpoint does not exist on the proxy this import would bind it to. Map the tool to a proxy that has the endpoint, or add the endpoint there, and import again."
}

Fix: add the missing endpoint to the target proxy, or map the tool to a proxy that already has it.

Note

Importing an MCP gateway that exposes another API Proxy's endpoints as tools (withDependencies=true, with includeReferencedProxies either true or false) requires the destination to be on Apinizer 2026.09.3 or later — such a package cannot be imported into an earlier installation.

En son tarihinde güncellendi