Upgrade Guide

Use the following guide to upgrade from the v1 dashboard to the new dashboard. If you are a new user of Cosmic, you can go ahead and sign up and skip this guide.

New dashboard information

  1. Location: https://app.cosmicjs.com
  2. REST API version: v3
  3. GraphQL API version: none

v1 dashboard information

  1. Location: https://app-v1.cosmicjs.com
  2. REST API versions: v1, v2
  3. GraphQL API versions: v1,v2,v3

Important notes

  1. Even if you have an account on the v1 dashboard, to use the new dashboard, you will need to create a new account with the new dashboard. Create one here.
  2. The new dashboard and latest API version (v3) are production ready.
  3. The new dashboard and API v3 are completely isolated from the v1 dashboard and prior API versions (v1, v2). This means that anything you do in the new dashboard WILL NOT affect anything currently in production or connected to the v1 dashboard or prior API versions. This is to ensure a smooth upgrade process with no possibility of breaking anything currently in production connected to the v1 dashboard and APIs.
  4. Though we are going to continue to provide access to the v1 dashboard for the time being, we encourage you and your team to start preparing to upgrade to the new dashboard sooner than later. We will announce a deprecation date of the v1 dashboard when the new dashboard is in general availability. We will be sure to provide you with ample time to upgrade safely and comfortably.


Before upgrading, make sure you read the changelog for details on new features, improvements, and any possible breaking changes from the v1 dashboard and API.

Upgrade steps

To upgrade to the new dashboard follow the steps below:

  1. Export Bucket from the OLD dashboard
    1. Log in to the OLD dashboard and download your Bucket export file found in Bucket Settings > Import / Export and have it ready to import into the new dashboard. If you have a very large Bucket, you may want to check the option to send the export via email.
    2. Find the area on this page that says “Dashboard v2 compatibility” to note any compatibility issues that may occur with the migration. These can be fixed in the v1 dashboard, or in the new dashboard.
  2. Sign up and log in to the NEW dashboard
    1. Sign up for the new dashboard (it will require a new sign up and takes seconds to complete).
    2. Create a new project and Bucket from scratch and go to Bucket Settings > Import / Export.
    3. Upload your Bucket export file into your new Bucket. If you have a very large Bucket, it may take some time.
    4. After the import is complete, you should see all of your Bucket content populated in the new dashboard.
  3. Testing
    1. Test your content by adding and editing Objects, doing your content editing workflows, making sure everything is working properly in the new dashboard.
    2. Connect the new API (v3) to your existing Cosmic-powered applications using the new API access keys (found in the dashboard Bucket Settings > API Access) to make sure everything is working properly in your application.
    3. Note the changelog for any updates that may require your attention. If you were using the v1 Cosmic NPM module, we have a new Cosmic JavaScript SDK connected to the v3 API. See the API reference for instructions on how to install.
  4. Inviting team members, upgrading, deploying to production
    1. When you have thoroughly tested the new dashboard and API with your application, and confirmed production readiness, the next step is to invite your team members for further testing. This may require a plan upgrade.
    2. The next step is to deploy your application to production connected to the v3 API.
  5. Removing projects from the v1 dashboard
    1. After you have completely moved your projects over to the new dashboard and API, deployed your app to production, you can safely delete your projects from the v1 dashboard.

Contact us

Reach out to Cosmic support if you run into any issues or have any questions. You can also join us in our Slack channel. We are also available for a call with your team to provide dedicated support for your upgrade.

We hope you enjoy using the new dashboard and we can’t wait to see what you build! 🛠️🚀