The new Cosmic dashboard is now available in private beta 🎉
Get it now →

Cosmic Changelog

Follow the changelog for release news, product enhancements, and new features.

New dashboard private beta and API v3 release

We are excited to announce the release of the new dashboard in private beta along with the API v3. This release has been a long time in the making and we are looking forward to helping you upgrade to the new dashboard and API for production use. 

Below is a list of changes that you should be aware of. Sign up for the new dashboard to get all of the latest features noted below.


  • 🎉 The new dashboard, API, and NPM module are ready for private beta customer upgrade.
  • ⚠️ Potential breaking change: Object models are now strongly typed and strictly connected to the Content Type model.
  • ⚠️ Potential breaking change: Parent Metafields cannot contain other Parent Metafields. Repeaters cannot contain Parent Metafields.
  • ⚠️ Potential breaking change: depth now required for all API requests past the first level.
  • ✨ Feature improvement: API metadata write improvements.
  • ✨ Feature improvement: Media validation by type and size.
  • ✨ New Feature: Content Type folders.

What’s new?

  1. New Cosmic dashboard now ready for customer upgrades
  2. New Cosmic API version (v3)
  3. New Cosmic NPM module (@next v5.0.0)

We’ve rebuilt the dashboard and the API from the ground up. Importing from dashboard v1 to v2 should be smooth as long as your modeling is compatible. Please note the breaking changes which may require updates to your content modeling to upgrade to the new versions.

Compatibility checking
In the old dashboard,  go to  Bucket Settings > Import / Export and find the area titled “Dashboard v2 compatibility” to note any compatibility issues that may occur with the migration. These can be fixed in the old dashboard, or in the new dashboard.

🔒 Content Type modeling locked - Potentially breaking

** Object Types are now called Content Types. **

In the old dashboard, Objects could individually have a different content model than the Content Type model. This has proven to be an undesired behavior, especially since we rolled out Singleton Content Types which better satisfies the use case for unique Object models.

In the new dashboard, Objects are now strongly typed and strictly connected to the Content Type model. This includes when making any changes to keys, adding Metafields, deleting Metafields or updating the order of Metafields.

Metafield modeling restrictions - Potentially  breaking

** Parents are now only allowed at the first level **

We have made updates to allowable Metafield modeling which may break some modeling:

  1. Parent Metafields are now only allowed at the first level. Parent Metafields cannot contain any other Parent Metafields.
  2. Repeater Metafields cannot contain Parent Metafields.

📁 Content Type folders - New feature

Content Type folders are now available to help you better organize your Content Types. This should be a welcome feature for those of you who are using Cosmic to store and manage a lot of different Content Types.

📍API updates - Improvements

  1. Depth update
    In the API v3, if you are using the the high-level metadata set in props, you will now need to include the depth parameter to retrieve nested Object data. For example, if you have Blog Posts that have an Object Metafield in the model connected to Authors, to retrieve the Author Object along with Blog Posts, you will need to set the depth parameter to 1.

    depth:0 returns the Object id (string)

      "title": "My Blog Post",
      "slug": "my-blog-post",
      "metadata": {
        "author": "asdfasdf12341234"

    depth:1 returns the nested Object data (object)

      "title": "My Blog Post",
      "slug": "my-blog-post",
      "metadata": {
        "author": {
          "id": "asdfasdf12341234",
          "title": "John Doe",
          "slug": "john-doe"

    The default depth value is 0. This is only applicable if you have metadata included in props without any further name-spaced declarations. Circular references are prohibited.

  2. API Metafield updates

    Objects no longer return metafields from the API, only metadata. You can still get metafields from the Content Type from the API.

    Metafield values are now strongly typed, so any Metafields that do not have values set will return as null. For example, if you don’t set a value on a Number Metafield, it will now return null instead of empty string.

🪄 Dashboard - Adding / editing Objects - Improvement

Adding and editing Object Metadata via the API got a lot better.

Before 😫
Before, adding Metadata was cumbersome requiring you to explicitly state all Metafield properties and values when making your edit Object API request.

Now 🥳
Now you only need to include the metadata values. Much simpler and concise.

🖼️ Dashboard - Media Metafield validation - Improvement

We have added new Media Metafield validations to enable you to restrict Media Metafields to images, audio, video, and document file types. Along with granular file type restrictions, you can also include a maximum file size to help guide your content creators to optimize your content creation and Bucket file storage.

Media previews are also much improved, giving you the ability to preview video, audio, and PDF files.

🆘 Migration Troubleshooting

There may be issues when you attempt to import from the old dashboard into the new dashboard. Some common issues may be:

  1. Object and Content Type Metafields model issues
    • To make sure that your Bucket is compatible with the new dashboard, in the old dashboard go to Bucket Settings > Import / Export and find the area on this page that says “Dashboard v2 compatibility” and test your Bucket compatibility. If any issues are reported, they can be fixed in the old dashboard, or in the new dashboard after import.
    • Object Metafield models are now strongly typed and strictly tied to their Content Type. This should come as a welcome change, but could be an issue if, in the old dashboard, you had single Objects that were composed of a different Metafield model than the Content Type. To fix this, make sure that your Content Type model is accurate for all Objects, and if you do have Objects that need a unique Metafield model, create a Singleton Content Type to store this single Object instead.
  2. If importing a Bucket into the new dashboard that previously contained modeling that is not supported, it will be ignored. IE: if you have a Parent inside of a Parent Metafield or any other unsupported Metafield model.

🏗️ Product architecture and pricing updates

The product architecture has been updated to two main usage levels:

  1. Projects
    • Projects contain Buckets. You can have multiple Buckets in a Project plan.
    • Add ons are available at the Project level and shared on all Buckets in the Project.
    • Team members are added and managed in the Project. Granular roles and permissions are available.
    • Usage reports are available in the Project. Filter by Bucket usage.
    • Billing is handled at the Project level. See Project > Billing > Plan for new pricing details.
  2. Workspaces
    • Workspaces contain Projects. You can have multiple Projects and Buckets in a Workspace plan.
    • Add ons are available at the Workspace level and shared on all Projects and Buckets in the Workspace.
    • Team members are added and managed in the Workspace. Granular roles and permissions are available.
    • Usage reports are available in the Workspace. Filter by Project and Bucket usage.
    • Billing is handled at the Workspace level. See Workspace > Billing > Plan for new pricing details.

➡️ Features TBD

There are a few features that we are still working on, but are planning on including them in a future release:

  1. Merge Requests
    • Offers git-like workflows for your content. Including visual change review and team member approvals.
  2. Single Sign On
    • Offering teams a way to login using a 3rd party IdP
  3. Workspace subdomain
    • Offering teams their own workspace subdomain.
  4. Mobile dashboard access
    • The new dashboard is currently desktop only.
  5. CLI connected to API v3

This is a big release for us and we hope you enjoy all of the updates. Sign up for the new dashboard to reserve your spot in line. Follow us on Twitter and join our Slack community to stay up with the latest updates.

NPM module updates - v4.2.*

We are excited to roll out new updates to the Cosmic NPM module (v4.2.*). This update adds new chain-style methods (Note: there are no breaking changes). Review the updates below.

Getting Started

Get started by installing the latest module version npm install cosmicjs@latest then import the package into your app.

Then set your Bucket slug and read key. These can be found in Your Bucket > Settings > API Access after logging in to your Cosmic dashboard.

Now use the new chain methods to find, add, edit, and delete Objects and Media in your Bucket.


  • Updated the NPM module to v4.2.*
  • Chain methods are now available
  • Breaking changes: none

What's new

  1. Added chain methods for Objects:
  • bucket.objects.find
  • bucket.objects.findOne
  • bucket.objects.insertOne
  • bucket.objects.updateOne
  • bucket.objects.deleteOne
  1. Added chain methods for Media:

Old methods

For the old npm-v4.1.19 methods, see the docs version for npm-v4.1.19. These methods include:

  1. Objects
  • bucket.getObjects
  • bucket.getObject
  • bucket.addObject
  • bucket.editObject
  • bucket.deleteObject
  1. Media
  • bucket.getMedia
  • bucket.getSingleMedia
  • bucket.addMedia
  • bucket.deleteMedia

We hope you enjoy these new methods for using the Cosmic NPM module. Review all of the methods now available in the Cosmic docs. To stay up with the latest updates to Cosmic, follow us on Twitter, subscribe on YouTube, join us on Slack.

New docs examples

We've added new examples to the Cosmic documentation to help you learn common Cosmic API methods and use cases. The new examples feature simple copy + paste code for Node.js, cURL, GraphQL, and the Cosmic CLI.

You can run the following code as is or add your Bucket access keys to connect to your Bucket content. Learn all of the available examples and follow along with the code examples below which use the Cosmic NPM module.

Go to the Cosmic docs to check out the new examples.

Setup & running Node.js

To run the following code examples, make sure you have Node.js installed on your machine. Then run the following setup commands in your terminal to make the Cosmic NPM module available in a new Node.js project:

mkdir cosmic-example
cd cosmic-example
yarn add cosmicjs

Add any of the code examples below to an index.js file and run node to see the results:

node index.js

Basic queries

The basic queries show you how to get a list of Objects in your Bucket by Object Type as well as getting a single Object in your Bucket by Object slug.

Get Objects by type:

Get single Object by slug:

Advanced queries

The advanced queries show you some of the capabilities to get content by more detailed search options such as metadata values, $gte (greater than or equal to), $lte(less than or equal to), $ne (not equal to), and more.

Search Objects by metadata value:

Search Objects by metadata number value less than or equal to using $lte:

Search Objects not equal to metadata value using $ne:

Check out more examples of advanced queries in the docs.

Other Examples

Other examples include adding a new Object and uploading media using React Dropzone.  Copy + paste the code, add your Bucket access keys, and run the code to learn how to add content to your Cosmic Bucket.

We hope you enjoy these additions to our extensive documentation to help you better implement Cosmic-powered content into your websites and apps. Check out the Cosmic docs examples section and let us know what you think!

Deprecation of Cosmic Functions

Cosmic Functions, which we announced back in 2018, is now scheduled for deprecation.

When will it be removed?
If you have used this feature, it is scheduled for removal in the current dashboard (and will not be included in the new dashboard).

You can continue to use the feature until the removal date. The date for removal from all new and existing Buckets is March 29, 2022*

* This will not affect any aspects of the core content management product or service.
** If you have already deployed functions to your AWS account through Cosmic, this will not affect the status of those functions. You will still be able to manage your functions through AWS.

Why is it being deprecated?
At the time we released Cosmic Functions, there were not a lot of options to deploy simple serverless functions easily in a dashboard interface. We actually used it quite a bit for some use cases internally, but they proved to not be very useful for our customers. And today there appears to be more (better) options in the marketplace for serverless function deployment including Serverless, Netlify, Vercel, and more.

We have decided to sunset the feature so we can focus more efforts on our core content management and delivery products and services.

Contact Us
If you have any questions or concerns about the removal of this feature please contact support.

Thank you,
Tony Spiro
Cosmic CEO

Webhook Props Now Available

You can now set props on webhooks to limit the data payload. This is useful for Objects with large data payloads as it allows you to limit the payload to just the data you need.

How to use the new feature
See the props section in the Cosmic docs to learn more about how to use props. Go to Your Bucket > Settings > Webhooks after logging in to use the new feature.

Let's look at a couple of example webhook payloads with and without props.

Without Props
You get the full data payload.

That's a lot of data! Do you need it all? Maybe not. Enter props.

With Props
Get only the data you need. This example sets slug,title,metadata

Go to Bucket Settings > Webhooks to set props.

Wow, that's nice! Notice how much more concise the data payload is compared to not using props. Keep in mind that this currently only applies to first-level props (namespaced metadata declarations are not supported yet).

We hope you enjoy this quick update to make your automated workflows with webhooks more efficient. If you have any questions, please join the conversation in the Cosmic Slack channel and reach out to us on Twitter.

Usage and Overage Policy Updates

New usage graphs in the dashboard 📊

We are thrilled to tell you that Cosmic is growing faster than ever. As we serve an ever-increasing amount of content to billions of users globally we will continue to scale and provide you with the best content management experience in the world. To that end, we are implementing a new usage and overage policy, specifically the usage of our global CDN.

Our global CDN includes several points of presence located around the world to serve API and media resources blazing-fast within milliseconds. Along with our generous usage limits of non-cached API requests and media storage, we have added additional usage verticals of our global CDN which include:

  1. Cached API requests - Number of read requests after initial request per month
  2. Media requests - Number of media requests per month
  3. API bandwidth - Amount of API bandwidth served per month
  4. Media bandwidth - Amount of media bandwidth served per month

Pricing page updates
Go to the pricing page to see the new overage policy and applicable costs for each usage plan. We have provided very generous limits on all plans and include a new table to inform you about the new overage costs.

New usage graphs
To track your Bucket usage, go to Bucket Settings > Usage to see new usage graphs.

Overage costs
If you are one of the few customers that will have overage costs, you will be charged at the start of the month for the full overage usage of the previous month. The first overage invoices will go out at the start of August for July 2021 usage.

To see any upcoming month-to-date overage invoices, go to Bucket / Group Plan Settings > Billing (or Account Settings > Billing Details if you added a plan since our Billing update).

To avoid overage charges, you can always upgrade to the next usage plan level at any time. Reach out to if you need a custom quote.

We are dedicated to providing you with the best content management experience in the world. And these updates are intended to help you track and scale your global content delivery as your business meets the demands of the growing digital economy.

If you have any questions about this policy update, you can reach out to me directly in the Cosmic Slack channel or by email.

Tony Spiro
Cosmic CEO

Account Billing Updates

We've made some dashboard updates that should make managing account information, billing, and payment methods on your Cosmic account much easier. To get started, go to Account Settings > Billing Details to set up your payment methods and manage your global billing for your Cosmic products and services.

New Payment Methods Manager
You can now add and manage payment methods directly on your user account from your account settings area. Before, billing for Buckets was handled on the Bucket settings page. Now, with payment methods managed by your user account, you can manage billing for multiple Buckets and add-ons without re-entering payment information. Plus, you can now use Google Pay!

Go to Account Settings > Billing Details to set up your payment methods.

Add Billing Details
Along with this new way of managing your billing and payment methods, you can now update the name, email, and additional information that will be available on your invoices. Payment history will also be available on your account Billing Details page. (For the old Bucket billing, you will still see payment history on the Bucket billing page)

Group Plans for Bulk Rate
Group plans (formally called Billing Packages) are available for grouping Bucket usage plans onto a single cost-savings bulk-rate plan. Choose between 5 and 10 Buckets, plus a 10% discount for yearly plans.

Transfer Billing
Transfering billing between members of your team is now easier than ever. To have another team member take over billing, simply have them click "Transfer Billing" and the billing will switch to their account. (Team members must have admin access on the Bucket to transfer billing). See screenshot below.

We hope you enjoy these updates to make it easier to manage your account and billing details. If you have any questions, you can reach out to us at

Docs updates + GraphQL + NPM + CLI updates

We have some exciting updates to share with you which includes:

  1. Documentation improvements: Client tabs, better nav, and more
  2. New versions of the GraphQL, NPM, and CLI clients
  3. New GraphQL API Postman collection
  4. Ability to ignore the cache (handy for real-time updates)
  5. Dashboard updates

Read more about the updates below, or jump over to the updated docs to get started. Go to the docs →


1. Documentation
Our new documentation website just got a lot better. We've added new tabs to show you the multiple methods for each resource including REST, Node.js, GraphQL, and the CLI.

2. New client versions
We have new GraphQL API (v3), NPM (v4), and CLI (v2) versions available that parallel the new features in the REST API v2 and follow the same request and response formats. See the docs changelog for the updates.

3. Postman collection for GraphQL API
Along with the REST API, we now have a Postman collection for the GraphQL API.

4. Ignore cache (real-time updates)
You can now ignore the cache for your API requests by setting use_cache=false as a query parameter in your GET requests. Why would you want to ignore our globally-fast CDN? This is helpful if you are doing real-time updates. For example, if you make an update to Object and immediately want to return the updated Object (as the cache takes ~200ms to purge).

5. Dashboard quality of life improvements
We've updated the Bucket settings page to include links to each section. We think this is a more helpful way to organize your Bucket settings.

We hope you enjoy these new updates. Head over to the new documentation site to check out all of these updates. And ping us in Slack if you have any questions.

Announcing the Cosmic REST API v2, New Docs

We are excited to introduce Cosmic REST API v2 (alpha). The API has been rebuilt from the ground up to be lighter, faster, with lots of new features to make building Cosmic-powered apps even better.

Along with this release, we've built a brand new documentation site to help you learn more about all the new features. We recommend you start there to get all the latest and greatest in this release. Read below to get a breakdown of the new features, improvements, and changes.

New Features

  • Nested metadata props are now possible without limit. See examples of nested props.
  • No depth limit for Object relationships. The only limit is the prevention of infinite recursion.
  • We now offer a Postman collection to review and demo all REST API methods.
  • You can now use the after param for Object pagination.
  • We now have endpoints for Metafields and Media Folders to do CRUD operations directly.


  • Lighter codebase, faster endpoints. In some cases, endpoint response times are up to 50% faster (non-cached).
  • Better endpoint structures that follow standard REST conventions such as POST /resources, GET /resources/:resource_id, etc.
  • Consistent error responses with verbose messages.
  • The Select Dropdown Metafield now includes both key and value in the API response.


  • _id has been changed to id.
  • type_slug has been changed to type.
  • status can now either be published or any (which returns latest Object version draft or published).
  • query is now the primary method for fetching and filtering Objects (Advanced Queries from v1). See Queries and Logic for examples.
  • Single Objects must now be fetched using id. To fetch by slug, you will need to use query.
  • write_key will now be required in the request header as Authorization Bearer.
  • metafields are hidden by default.
  • Stricter user input requirements. No additional fields are possible in the body for POST and PATCH requests.
  • There is a new, more secure token authentication strategy.

Next Steps

Read the docs to learn more about all the updates and improvements. We would appreciate your input as we get the REST API v2 ready for production. If you have any comments or questions, please drop them in the comments below or in our Slack channel.

- Cosmic Team

Get started with Cosmic

Personal projects are free. Scale up as you grow.
Start building Talk to sales