Import content with the Management API
Bring entries, blocks, images, references, translations and redirects into CMS Orbit from any source with the cms-orbit import command, with a dry run first and safe to run again. The migration guides build on it.
How-to guide12 min read
Moving content into CMS Orbit has two halves. The first reads the old system and turns its content into a neutral file. The second reads that file and writes it into CMS Orbit with the Management API. This guide is the second half: the import file, and the cms-orbit import command that reads it, the same for every source. The guides for Contentful, Storyblok, Sanity and WordPress each write the first half. Plan a migration to CMS Orbit covers the rest of the project: the inventory, the model, validation, redirects and launch.
The command:
- checks the whole file with
--dry-runfirst, without changing anything, and lists every problem a real run would meet; - uploads every image once and sets its alt text in each language;
- creates entries with their fields and blocks, and fills in references and links between them in a second pass, so the order of the file does not matter;
- copies each entry into the other languages, linked as translations, then writes the translated text;
- adds redirects from the old addresses;
- keeps each entry's id from the old system on the entry, so running it again updates instead of making duplicates;
- publishes only when you ask.
It comes with the JavaScript SDK and needs Node 20 or later. Run it with npx, no install needed.
Before you start
- The schema. Create the content types and components first, with Schema as code or under Schema in CMS Orbit. The import refuses fields and blocks the schema does not have.
- Regions and languages. Create the region and every language you import into, in CMS Orbit or with the Management API (see "Environments, regions and languages" in the Management API reference). Language codes are BCP 47, such as
en-GBandnb-NO. - A management token (
cms_mt_…) from Organisation › Management tokens, created by someone who may create content, upload media, copy to other languages and manage redirects in that space. - Shared sections. If you import shared sections into a new space, open the space in CMS Orbit once first: the shared section content type is added the first time the space is opened.
- Import into Staging. Check everything there, then promote to Production. Run test imports in a space of their own, with entry names starting
TEMP, and delete it afterwards.
How CMS Orbit stores what you import
{locale}/content with name, contentTypeKey, slug, fields and components. It is saved as a draft.slug, or the content type's address prefix, such as /journal. Send urlOverride to keep an exact address.{ "type": "textSection", "fields": { … }, "children": { "items": [ … ] } }. Blocks inside a slot go in children under the slot's key. Ids are added for you.h1 becomes h2, and images, scripts, styles and embeds are removed./media, then send its id in an Asset field.{ "kind": "content", "contentId": "<id>" }. Any other address is { "kind": "url", "href": "/gear/fjell-gtx-boot" }.{locale}/copy, then updated. Copies are linked as translations, so the language switcher, hreflang and references between languages work./redirects/import, up to 5,000 per file.{locale} stands for /environments/{environmentId}/regions/{regionId}/locales/{localeId}, and every address starts with https://api.bifrostorbit.com/cms/manage/v1/organisations/{organisationId}/spaces/{spaceId}.
1Write the import file
The file describes where the content goes and every entry, with three placeholders the command replaces:
{ "$asset": { "url": "…", "alt": "…" } }alt is text in the main language, or an object with a text per language code.{ "$ref": "<key>" }key, in the same language{ "$link": "<key>" }keyEach entry has a key of your choosing, usually its id in the old system. A Northwilds example:
{ "environment": "staging", "region": "europe", "locale": "en-GB", "translations": ["nb-NO"], "entries": [ { "key": "author:ingrid", "type": "author", "name": "Ingrid Berg", "slug": "ingrid-berg", "fields": { "bio": "<p>Ingrid leads our winter trips from Tromsø.</p>", "photo": { "$asset": { "url": "https://old.northwilds.com/media/ingrid.jpg", "alt": { "en-GB": "Ingrid Berg on a ridge above Tromsø", "nb-NO": "Ingrid Berg på en fjellrygg over Tromsø" } } } } }, { "key": "section:newsletter", "type": "sharedSection", "name": "Newsletter sign-up", "components": [{ "type": "textSection", "fields": { "heading": "Get the Journal", "level": "h2", "text": "<p>One email a month.</p>" } }] }, { "key": "post:lofoten", "type": "journalPost", "name": "Lofoten in winter", "slug": "lofoten-in-winter", "url": "/journal/lofoten-in-winter", "fields": { "excerpt": "What to pack for a week of short days and big views.", "publishedOn": "2026-01-14", "author": { "$ref": "author:ingrid" } }, "components": [ { "type": "text", "fields": { "text": "<h2>Before you go</h2><p>Pack light.</p>" } }, { "type": "gearList", "fields": { "heading": "What we bring" }, "children": { "items": [ { "type": "gearItem", "fields": { "name": "What to pack", "link": { "$link": "post:pack" } } }, { "type": "gearItem", "fields": { "name": "Fjell GTX boot", "link": { "kind": "url", "href": "/gear/fjell-gtx-boot" } } } ] } }, { "type": "sharedSection", "fields": { "section": { "$ref": "section:newsletter" } } } ], "seo": { "title": "Lofoten in winter", "description": "What to pack for a week of short days." }, "translations": { "nb-NO": { "name": "Lofoten om vinteren", "slug": "lofoten-om-vinteren", "url": "/journal/lofoten-om-vinteren", "fields": { "excerpt": "Hva du bør pakke for en uke med korte dager." } } } } ], "redirects": [{ "from": "/blog/lofoten-in-winter", "to": "/journal/lofoten-in-winter" }]}environment, region, localetranslationsentries[].keyentries[].folderIdentries[].typesharedSection for a shared section.entries[].name, slug, urlentries[].fields, components, seoentries[].translationsname, slug, url, fields, components and seo. fields are merged over the copied ones; components replace the copied blocks. Leave out what is not translated.redirectsfrom an old address to a new one, with an optional status (301, 302, 307 or 308)2Check it with a dry run
The command reads the token, organisation and space from the environment, or from .env.local or .env in the current folder:
export ORBIT_TOKEN=cms_mt_…export ORBIT_ORGANISATION=<organisation id>export ORBIT_SPACE=<space id>npx -p @bifrost-orbit-cms/sdk cms-orbit import import.json --dry-runIf the SDK is already in your project, npx cms-orbit import import.json --dry-run is enough.
A dry run sends every entry to CMS Orbit to be checked as if it were saved, then throws the result away. It checks fields against the content types, blocks against the components, addresses, links, every file's address, the translations and the redirects, and changes nothing:
Checking 4 entries into staging · europe · en-GB would create sharedSection Newsletter sign-up would create author Ingrid Berg would create journalPost Lofoten in winter would create journalPost What to pack would translate Lofoten in winter into nb-NO4 would be created, 0 would be updated, 4 would be copied into other languages, 1 would be translated.2 files checked, 0 already uploaded.Redirects: 1 would be added, 0 would be changed, 0 unchanged.Problems are listed together at the end, such as post:lofoten: POST …/content?dryRun=true answered 400: Some fields are invalid: fields.conditions: "muddy" is not one of good or icy, and the command exits with 1. Fix the import file or the schema and check again until there are none.
Two things a dry run can't check: a reference to an entry the same run would create is only filled in on a real run, and publishing checks, such as alt text and required fields, run when you publish.
3Import it
npx cms-orbit import import.jsonImporting 4 entries into staging · europe · en-GB created sharedSection Newsletter sign-up created author Ingrid Berg created journalPost Lofoten in winter created journalPost What to pack translated Lofoten in winter into nb-NO4 created, 0 updated, 4 copied into other languages, 1 translated.2 files uploaded, 0 already uploaded.Redirects: 1 added, 0 changed, 0 unchanged.Each entry's key is kept on the entry as its external ID. The next run finds the entries by it and updates them instead of making new ones, and only copies entries that are not yet in a language. Editors see it under Details in the entry's info panel. There is no state file to keep: you can run the import from another computer or a CI job and it finds what the last run made. $ref and $link may also name the key of an entry made by an earlier import, which is useful when you import in parts, such as authors first and posts later.
The command also writes import.json.<space id>.assets.json beside the file, with the files it uploaded, so the next run doesn't download them again. Deleting it is safe: uploading the same file again answers with the stored one.
When an entry is refused, the command reports it, carries on with the rest and exits with 1 at the end. Fix the problem and run it again: what was already made is updated. Error codes lists every status.
--dry-run--publish--token, --organisation, --spaceORBIT_TOKEN, ORBIT_ORGANISATION and ORBIT_SPACE--apiORBIT_API4Use the API yourself
To write your own import, in another language or with steps of your own, the command is a guide to the calls it makes:
- GET
{locale}/content?externalId=<key>finds entries by their external ID. RepeatexternalIdfor up to 500 at once. - POST
{locale}/contentwithexternalIdcreates an entry with it. Another entry in the same language with that external ID answers409. ?dryRun=trueon POST{locale}/contentand PATCH{locale}/content/{id}runs every check and answers what would be saved, without saving.- POST
/redirects/importwithapply: falsepreviews redirects.
See Management API for the rest.
5Check and publish
Open a few entries in CMS Orbit and check them in the preview: blocks in order, images with alt text, links going to the right pages, translations in place. Then publish, in CMS Orbit or by running the import with --publish:
npx cms-orbit import import.json --publishPublishing runs the same checks as the Publish button. The command reports each entry it could not publish and carries on, for example:
Before publishing, add alt text to ridge.webp in the media library.Every image needs alt text in the language being published. Add it in the import file or the media library.
Entries that are already published with no changes are skipped.
Promote to Production once Staging is right, with their redirects:
npx cms-orbit promote --from staging --to production --region europe --locale en-GB --dry-runnpx cms-orbit promote --from staging --to production --region europe --locale en-GBAdd --folder <folder id> to promote one folder, and run it once per language. Editors can do the same from Pages. See Promote a folder or a language.
Things to know
- Rich text keeps no images. Split images out of the old rich text into blocks, as every migration guide does. Embedded entries become blocks or references in the same way.
- Links inside rich text are plain addresses. They do not follow a page that moves. Rewrite old addresses to new ones while you transform, and use Link fields where a link must follow its page.
- Every entry of your own content types has an address. Supporting entries such as authors get one too: give them a slug, and decide whether your website shows a page for them.
- Files are stored once. Uploading a file CMS Orbit already holds answers with the existing file. Images are converted to WebP where that makes them smaller. Up to 25 MB per file.
- Alt text is set per language, as a whole. PATCH
/media/{id}withaltreplaces the alt text of every language, so send all of them together. - One request at a time. The command sends requests one after another on purpose, and waits and tries again when the server is briefly busy. A migration of a few thousand entries takes minutes.
- A create that times out doesn't repeat. If the answer was lost, the next run finds the entry by its external ID and updates it.
- External IDs are unique in each language, up to 200 characters. Prefix them with the source, such as
wp:post:12, so imports from two systems can't collide. A copy into another language or environment keeps it; a duplicate in the same language doesn't. - Folders: entries go at the top level, with addresses from the content type's prefix or
url. To build a folder tree, create folders with POST{locale}/foldersand give entries afolderId.
Change content in bulk later
The same calls work for changes after the migration, such as filling a new field from an old one:
- List the entries of a folder with GET
{locale}/content?folderId=rootor byfolderId. - Read each one with GET
{locale}/content/{id}. Itsdraft.fieldsanddraft.componentshold the content, anddocVersionits version. - Send PATCH
{locale}/content/{id}with the wholefieldsobject anddocVersion. If someone saved it in between, the answer is409: read it again and retry.
Was this page helpful?