Skip to content

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-run first, 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-GB and nb-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

An entry
What to send
POST{locale}/content with name, contentTypeKey, slug, fields and components. It is saved as a draft.
Its address
What to send
From its folder and slug, or the content type's address prefix, such as /journal. Send urlOverride to keep an exact address.
A block
What to send
{ "type": "textSection", "fields": { … }, "children": { "items": [ … ] } }. Blocks inside a slot go in children under the slot's key. Ids are added for you.
Rich text
What to send
An HTML string. It is cleaned on save: h1 becomes h2, and images, scripts, styles and embeds are removed.
An image
What to send
Upload it with POST/media, then send its id in an Asset field.
A reference
What to send
The other entry's id, in the same language.
A link to a page
What to send
{ "kind": "content", "contentId": "<id>" }. Any other address is { "kind": "url", "href": "/gear/fjell-gtx-boot" }.
A translation
What to send
A copy of the entry in another language, made with POST{locale}/copy, then updated. Copies are linked as translations, so the language switcher, hreflang and references between languages work.
A redirect
What to send
A row of POST/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": "…" } }
Becomes
The id of the uploaded file. alt is text in the main language, or an object with a text per language code.
{ "$ref": "<key>" }
Becomes
The id of the entry with that key, in the same language
{ "$link": "<key>" }
Becomes
A link to the entry with that key

Each entry has a key of your choosing, usually its id in the old system. A Northwilds example:

JSON
{  "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, locale
Means
The environment key, region key and language code to import into
translations
Means
Other language codes in the same region. Every entry is copied into each.
entries[].key
Means
Your own id for the entry, usually its id in the old system. References and links point at it, and it is kept as the entry's external ID.
entries[].folderId
Means
Optional: the id of the CMS Orbit folder to put it in
entries[].type
Means
The content type key. sharedSection for a shared section.
entries[].name, slug, url
Means
The entry's name, its slug, and optionally an exact address to keep
entries[].fields, components, seo
Means
As in the table above
entries[].translations
Means
Per language: name, slug, url, fields, components and seo. fields are merged over the copied ones; components replace the copied blocks. Leave out what is not translated.
redirects
Means
from 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:

Shell
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-run

If 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:

Text
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

Shell
npx cms-orbit import import.json
Text
Importing 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
Means
Check everything without changing anything
--publish
Means
Publish every entry, in every language, once it is imported
--token, --organisation, --space
Means
Instead of ORBIT_TOKEN, ORBIT_ORGANISATION and ORBIT_SPACE
--api
Means
Another Management API address, instead of ORBIT_API

4Use 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. Repeat externalId for up to 500 at once.
  • POST{locale}/content with externalId creates an entry with it. Another entry in the same language with that external ID answers 409.
  • ?dryRun=true on POST{locale}/content and PATCH{locale}/content/{id} runs every check and answers what would be saved, without saving.
  • POST/redirects/import with apply: false previews 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:

Shell
npx cms-orbit import import.json --publish

Publishing 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:

Shell
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-GB

Add --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} with alt replaces 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}/folders and give entries a folderId.

Change content in bulk later

The same calls work for changes after the migration, such as filling a new field from an old one:

  1. List the entries of a folder with GET{locale}/content?folderId=root or by folderId.
  2. Read each one with GET{locale}/content/{id}. Its draft.fields and draft.components hold the content, and docVersion its version.
  3. Send PATCH{locale}/content/{id} with the whole fields object and docVersion. If someone saved it in between, the answer is 409: read it again and retry.

Was this page helpful?

Read next

Plan a migration to CMS OrbitThe playbook for moving a website to CMS Orbit from any CMS: the phases from discovery to the weeks after launch, with deliverables, a safe import order, media, references, languages, redirects, validation, launch and rollback, a checklist to copy, and the guide for each source platform.Management APIEvery endpoint scripts and integrations use to change content, schema, media and settings, with tokens, permissions, bodies, answers, errors and limits.Schema as codeKeep your content types and components in your repository and create or change them from a script or CI with the Management API, with a dry run, safe field changes and generated types.Migrate from ContentfulMove a Contentful space to CMS Orbit: how Contentful's concepts map, exporting with the Contentful CLI, turning entries, rich text, assets, references and locales into an import file, and importing it with redirects.Migrate from StoryblokMove a Storyblok space to CMS Orbit: how stories, blocks, folders and languages map, datasources as taxonomies from their CSV, reading every story with the Content Delivery API, turning blocks, rich text, assets, links and relations into an import file, and importing it with redirects.Migrate from SanityMove a Sanity dataset to CMS Orbit: how documents, schema types, Portable Text, references and document-level translations map, exporting with the Sanity CLI, transforming to an import file, and importing it with redirects.Migrate from WordPressMove a WordPress site to CMS Orbit: how posts, pages, blocks, categories, media and SEO plugins map, reading everything with the WordPress REST API, splitting post HTML into blocks, and importing it with redirects from every old address.Migrate from DrupalMove a Drupal 10 or 11 site to CMS Orbit: how nodes, paragraphs, media, taxonomy terms, menus, path aliases and translations map, reading everything with JSON:API, turning paragraphs and body HTML into blocks, importing vocabularies as taxonomy CSV, and importing the rest with redirects.Migrate from Adobe Experience ManagerMove an AEM Sites site to CMS Orbit: how pages, components, Content Fragments, Experience Fragments, DAM assets, tags, language copies and live copies map, reading pages as JSON with the Sling Model Exporter and fragments with GraphQL, turning components into blocks and tags into taxonomy CSV, and importing it with redirects.Migrate from SitecoreMove a Sitecore site to CMS Orbit from SitecoreAI (XM Cloud) or XP 10: how templates, renderings, datasources, placeholders, the media library, language versions and redirect maps map, reading every page's layout with the Experience Edge GraphQL schema, turning components into blocks and data items into entries and taxonomy CSV, and importing it with redirects.Migrate from StrapiMove a Strapi 5 project to CMS Orbit: how collection types, components, dynamic zones, media, relations and i18n locales map, categories as a taxonomy from CSV, reading every entry with the REST API, turning dynamic zones and Blocks rich text into an import file, and importing it with redirects.Migrate from PrismicMove a Prismic repository to CMS Orbit: how custom types, slices, slice zones, locales and Integration Fields map, tags as a taxonomy from CSV, reading every document with the Content API, turning slices and rich text into an import file with a link resolver, and importing it with redirects.Migrate from HygraphMove a Hygraph project to CMS Orbit: how models, components, modular fields, union references, enumerations, assets, locales and the DRAFT and PUBLISHED stages map, reading every entry with the GraphQL Content API page by page, turning components and rich text into an import file, and importing it with redirects.Migrate from PayloadMove a Payload 3 project to CMS Orbit: how collections, globals, blocks fields, relationships, uploads, localization and drafts map, categories as a taxonomy from CSV, reading every document with the REST or Local API, turning blocks and Lexical rich text into an import file, and importing it with redirects.Migrate from DirectusMove a Directus project to CMS Orbit: how collections, fields, many-to-any builders, files, relations and the translations interface map, a topics collection as a taxonomy from CSV, reading every item with the REST API, turning builder blocks and WYSIWYG HTML into an import file, and importing it with redirects.Migrate from WebflowMove a Webflow site's content to CMS Orbit: how CMS collections, items, static pages, assets, Localization and 301 redirects map, a categories collection as a taxonomy from CSV, reading items and pages with the Data API v2, rebuilding static pages as blocks, and importing it all with redirects.Field typesEvery field a content type or component can have, its settings and rules, and how each one arrives in the delivery API and in generated types.