Import Objects

Endpoint

POST /apiops/projects/{projectName}/export-import/{type}/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 when the package is encrypted

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Target project name
type	string	Yes	Export/import type of the package, case-insensitive. See List Supported Types

Form Fields

Field	Type	Required	Default	Description
exportFile	file	Yes	—	The ZIP package. The file name must end with `.zip`
override	boolean	No	false	When `false`, the objects are imported as new. When `true`, a same-named object in the target project is replaced
environmentMapping	string (JSON)	No	—	Maps an environment name in the package to an environment name on this installation, for example `{"UAT": "Production"}`. An empty value marks that environment as deliberately not transferred. Without it, same-named environments match and unmatched ones are dropped. Applies to `override=false` (Import as New) only — with `override=true` the mapping is ignored, because Replace Existing merges onto the target object's own environment assignment, which the two `certEnvironment*` fields below govern
certEnvironmentMergeMethod	string	No	MATCH_BY_NAME	For certificate and key packages imported with `override=true`: `MATCH_BY_NAME` writes to the environments named in the package, `OVERWRITE_ALL` writes to every target environment
certEnvironmentUncoveredAction	string	No	—	For certificate and key packages imported with `override=true`: 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
acknowledgeChecksumMismatch	boolean	No	false	When `true`, a transfer-manifest finding that the package changed after export is accepted instead of rejected, and the import proceeds. This covers all three such findings: a package file whose content was edited or re-saved, a file added to or missing from the package (an entry-count mismatch), and a manifest that cannot be read or disagrees with the files in the package. The response then carries a `warn` advisory with key `transfer.checksumMismatchAcknowledged`, and the acknowledging user is written to the operational log. The parameter name is unchanged for compatibility. It does not widen a compatibility refusal — a manifest format newer than this installation understands, an unrecognised critical feature and an unsupported checksum algorithm are rejected with 400 regardless of this flag, as is a package file whose JSON cannot be parsed at all

Response

Success Response (200 OK)

{
  "status": "SUCCESS"
}

When part of the package could not be carried over, the response says so:

{
  "status": "SUCCESS",
  "unresolvedReferences": [
    "The following imported objects are not deployed to any worker: CERTIFICATE: partner-cert"
  ]
}

When the import ran with acknowledgeChecksumMismatch=true and the package did carry such a difference, the response also carries the advisory that records it:

{
  "status": "SUCCESS",
  "advisories": [
    {
      "level": "warn",
      "key": "transfer.checksumMismatchAcknowledged",
      "params": {
        "entryCount": 2,
        "acknowledgedBy": "ci-pipeline@example.com"
      }
    }
  ],
  "unresolvedReferences": [
    "transfer.checksumMismatchAcknowledged: entryCount=2 acknowledgedBy=ci-pipeline@example.com"
  ]
}

Response Fields

Field	Type	Description
status	string	`SUCCESS` or `FAILURE`
unresolvedReferences	array of string	What the import could not carry over — dropped references, blanked secrets, objects that still need deploying — as one rendered line per item. Absent when there is nothing to report
advisories	array of object	The machine-readable form of `unresolvedReferences`: each entry carries `level` (`error`, `warn`, `info` or `ok`), a stable `key` a pipeline can branch on, and `params` with the raw interpolation values. The `transfer.checksumMismatchAcknowledged` warn advisory (`params.entryCount`, `params.acknowledgedBy`) is added only when `acknowledgeChecksumMismatch=true` actually accepted a difference. `params.entryCount` is the number of distinct package entries the acknowledgment covered — a file is counted once per import, however many times the package is verified along the way. A changed file, a declared file missing from the package and an undeclared file present in it each count as one entry; an unreadable or self-contradictory manifest counts as one entry (the manifest itself), because there is then nothing left to attribute per file. Absent when there is nothing to report

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "Import as New cannot proceed: openai-prod (LLM_PROVIDER) — an object of this kind and name already exists in the target project. Use Replace Existing where the object already exists in this project, or rename the object(s) before importing."
}

Each rejected name carries its own reason, so a script can tell the three causes apart: already exists in the target project (Replace Existing is the remedy), this name is carried twice by this import package (the package itself is the problem), and already exists elsewhere on this installation … for object types whose names must be unique across all projects — credential usernames, environment variables, AI preset catalogs and model definitions. The last one is refused even when the target project holds no such object, and Replace Existing has nothing to update there:

{
  "status": "FAILURE",
  "resultMessage": "Import as New cannot proceed: svc-partner (CREDENTIAL) — an object of this kind and name already exists elsewhere on this installation (another project, the shared admin scope, or a built-in item) and this kind's names must be unique across ALL projects, not only the target project. Use Replace Existing where the object already exists in this project, or rename the object(s) before importing."
}

{
  "status": "FAILURE",
  "resultMessage": "This package holds no IP_GROUP object — it looks like a CREDENTIAL package; nothing was imported."
}

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

{
  "status": "FAILURE",
  "resultMessage": "User does not have required EXPORT_IMPORT permission for SECRETS to import this package!"
}

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

{
  "status": "FAILURE",
  "resultMessage": "Replace Existing of CERTIFICATE 'partner-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."
}

{
  "status": "FAILURE",
  "resultMessage": "Integrity check failed for 'openai-prod.json': its bytes differ from the exported ones since the package was exported. Use the export file Apinizer produced as-is, without editing or re-compressing it."
}

Common Causes

override=false and an object of the same name already exists in the target project
The package holds objects of a different type than the one in the path
The uploaded file is not a ZIP file, or its name does not end with .zip
The package carries objects whose asset categories the token lacks EXPORT_IMPORT on
The package is encrypted and no passphrase — or a wrong one — was supplied
override=true on a certificate/key package where the target has an environment the package does not cover, and certEnvironmentUncoveredAction was not supplied
The package changed since export — a file's content differs, a declared file is missing, an undeclared file was added, or the manifest itself cannot be read — and acknowledgeChecksumMismatch was not sent as true
The package carries a manifest format newer than this installation understands, declares a critical feature it does not recognise, or uses an unsupported checksum algorithm; these stay rejected even with acknowledgeChecksumMismatch=true
A JSON file inside the package cannot be parsed at all (a text editor replaced its quotes with smart quotes, for example); the entry is genuinely unreadable, so the flag does not apply
The package was produced by a very old installation and carries an LLM Provider, Vector DB or OpenTelemetry (OTLP) secret that is already encrypted. Importing it would encrypt the value a second time and destroy it, so the import is refused instead; re-export the package from the source installation with a current Apinizer version

Error Response (401 Unauthorized)

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

cURL Example

Example 1: Import as New

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/TargetProject/export-import/LLM_PROVIDER/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "exportFile=@openai-prod.zip" \
  -F "override=false"

Example 2: Replace an Existing Object

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/TargetProject/export-import/LLM_PROVIDER/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "exportFile=@openai-prod.zip" \
  -F "override=true"

Example 3: Map Environments While Importing

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/TargetProject/export-import/CERTIFICATE/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "exportFile=@partner-cert.zip" \
  -F 'environmentMapping={"UAT":"Production"}'

Example 4: Import an Encrypted Package

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/TargetProject/export-import/CREDENTIAL/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Apinizer-Package-Passphrase: $(printf '%s' 'my-passphrase' | base64)" \
  -F "exportFile=@partner-credential.zip" \
  -F "override=false"

Example 5: Acknowledge a Checksum Mismatch

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/TargetProject/export-import/LLM_PROVIDER/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "exportFile=@openai-prod.zip" \
  -F "override=false" \
  -F "acknowledgeChecksumMismatch=true"

Notes and Warnings

Dependencies bind by name: every object the package carries that already exists in the target project under the same name is bound to it; everything else is created. This is the automatic form of the "map to existing by name" step in the Apinizer interface.
Wrong-kind matches are never made: for the groups that carry several kinds behind one reference — connections, API creators, authentication services, MCP servers, A2A agents — only a same-kind object is an eligible match, so a database connection can never be bound to a file transfer connection.
Ambiguous matches are not guessed: when a packaged dependency matches more than one object by name, it is imported as new instead. A wrong binding would be silent and permanent; a duplicate is visible and can be fixed.
Read unresolvedReferences: it reports everything the import could not carry over. A package that transferred only partially never returns a bare success.
Secrets are not carried in the clear: secret values of imported connection objects are blanked and must be re-entered in the target project, unless the package itself was encrypted end to end.
Imported objects are not deployed: objects that need deployment to take effect are persisted but not pushed to the workers by the import. Deploy them afterwards.
Type must match the package: the type in the path is what the import looks for inside the package. If the package holds something else, nothing is written and the response names the type it actually found.
Package integrity is verified first: a package that carries an integrity record (apinizer-transfer-manifest.json, written by Export Objects) is checked before anything is persisted. A record that cannot be read, a file set that does not match it, a file whose content changed since export (any of the three acknowledgeable — see below), or a package format newer than this installation understands is rejected with 400 Bad Request, and nothing is written. As with the other refusals on this endpoint, the reason arrives as a sentence in resultMessage, naming the file at fault where there is one.
Older packages still import: a package produced before this record existed carries none, and imports exactly as it always did — the verification simply does not run. The check is what a package must pass when it has a record, not a requirement that every package have one.
Ship packages as produced: unzipping a package, editing a file and re-compressing it makes the file set or a fingerprint disagree with the record, and the import is refused unless the difference is acknowledged. Make the change at the source and export again.
Every "the package changed" finding can be overridden: acknowledgeChecksumMismatch=true accepts a file whose content changed after export, a file set that no longer matches the record (a declared file missing, or a file the record never mentions) and a manifest that cannot be read or disagrees with the package, and lets the import proceed; an unreadable manifest, once acknowledged, is treated as if the package carried none. The response then carries the transfer.checksumMismatchAcknowledged warn advisory (in advisories, and as a rendered line in unresolvedReferences) and the acknowledging user is written to the operational log. What the flag does not widen is compatibility: a manifest format newer than this installation understands, an unrecognised critical feature and an unsupported checksum algorithm are rejected with 400 Bad Request no matter what this parameter is set to, as is a package file whose JSON cannot be parsed at all.
A pipeline can branch on the advisory key: because transfer.checksumMismatchAcknowledged is a stable identifier rather than a translated sentence, an automated caller can detect that an import succeeded only because a mismatch was explicitly overridden — for example to flag the run for a human review, or to fail a stricter pipeline that expects byte-for-byte packages — without parsing resultMessage text.

Permissions

User must have the type's own asset category + EXPORT_IMPORT, or PROJECT_MANAGEMENT + EXPORT_IMPORT, in the target project
Every asset category present in the package is additionally checked against the target project, since that is where the objects land

Export / Import API - Overview and shared concepts
Export Objects - Produce the package imported here
List Objects of a Type - Verify what landed in the target project

Endpoint​

Authentication​

Header​

Request​

Headers​

Path Parameters​

Form Fields​

Response​

Success Response (200 OK)​

Response Fields​

Error Response (400 Bad Request)​

Common Causes​

Error Response (401 Unauthorized)​

cURL Example​

Example 1: Import as New​

Example 2: Replace an Existing Object​

Example 3: Map Environments While Importing​

Example 4: Import an Encrypted Package​

Example 5: Acknowledge a Checksum Mismatch​

Notes and Warnings​

Permissions​

Related Documentation​