Plan an import
const url = 'https://api.ebitex.io/content/management/v1/import-plan';const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.ebitex.io/content/management/v1/import-plan \ --header 'Authorization: Bearer <token>'Compares a bundle with the key’s environment and reports, per item, what an import would do. It writes nothing, so it is safe to run from a pull-request check with a read-only key.
identityMode says how bundle items are matched to what is already there: externalId (the default) matches on each item’s own natural key, which is what a content model kept in source control needs; preserve matches on the bundle’s ids; fresh treats every item as new.
Each item’s state is new, identical, update or conflict. A differing item is update only when you prove the environment has not changed since you last saw it: record each item’s stateToken under its naturalKey, and send that map back as baseTokens next time. Without a matching token every differing item is a conflict. An item whose realmKey names a realm above the key’s own is written into that realm, and its plan line says so with realmKey and realmName; every other item is written into the key’s realm. Realm keys are ignored for fresh and for a bundle from another organization. blockers lists anything that would make /import refuse: a component owned by an ancestor realm that the bundle would overwrite, an item owned by an ancestor realm that this key may not write to, or an existing component or page that differs from the bundle while its publishing workflow holds it in a state that does not allow edits, such as review. warnings includes one line starting quota: for each plan limit (components, pages, categories) that the items in state new would take the organization past. It is a warning, not a blocker, because leaving items out of the import can bring it back under. Send validate: true to also check every document the way an import does, in a transaction that is rolled back: each document an import would refuse comes back as a warning starting would_be_refused:. It costs about as much as the import itself, so it is off by default, and a bundle that creates categories is not checked (a validation_skipped: warning says so). A clean plan does not promise a valid import: the plan limits are checked again at import, and so are the documents when validate was not set. Plan again before every import; a plan is only true of the environment as it was when it ran.
Key: a management key with content.management.read.
Authorizations
Section titled “Authorizations”Responses
Section titled “ Responses ”{ "items": [ { "kind", "id", "externalId", "naturalKey", "name", "implicit", "state", "stateToken" } ], "warnings": [ … ], "blockers": [ … ] }. implicit marks an item that is present only as another item’s dependency. realmKey and realmName appear only on an item written into a realm other than the key’s own.
validation_failed: no body, bundle is not a bundle document, or identityMode is unknown. unsupported_format_version: the bundle’s formatVersion is not one this server accepts; the response gives supplied and supported. unknown_property: the body has a property this API does not recognize; the response names it in property. invalid_json: the body is not valid JSON.
missing_api_key or invalid_api_key: no key was sent, or it is unknown, revoked or expired.
payment_required: the organization’s subscription needs attention.
scope_denied: the key lacks this route’s scope. tier_required: the Content Management API needs the Pro plan or above. ip_denied: the caller’s address is outside the key’s allowed ranges. app_not_available: Content is not enabled for the organization.
Rate limit or quota exceeded; Retry-After says how long to wait. too_many_failed_authentications: too many bad keys from this address.