The new Cosmic dashboard is here!
Test drive it now →

Cosmic Changelog

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

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

Projects, Merge Requests, and other Updates

We've made a few big changes to the dashboard and API recently:

Projects are a new way to connect Buckets for use with Merge Requests. To do merges between Buckets they must be in the same Project. If you have Buckets that were created prior to the Merge Request release, you can clone any Bucket to create a new Project.

Clone Bucket from Settings
You can now clone any Bucket from the settings area by going to Settings > Basic Settings in the left sidebar, scroll down, and click "Clone Bucket". The Bucket will be cloned into the same Project (if it's not connected to a Project, a new one will be created).

Merge Requests

Merge Requests was the big release that we announced on Tuesday this week. Merge Requests enables you to do Git-like workflows for content. Perform bulk edits between Buckets, preview, include your team for approval workflows, and more. 

With this feature becoming a first-class feature in the Cosmic workflow, we've removed a previously released feature to copy Objects to another Bucket from the Objects table.

Merge Request Preview Link
You now have the ability to add a Merge Request preview link to your Bucket by going to Settings > Basic Settings and scrolling down to Merge Request Preview Link (only available on Buckets in a Project). This will be the default link added to all merge requests that make this Bucket the target Bucket.

There is a new webhook event available for merge.completed. This will only be triggered by the target Bucket. To set this up, in your Bucket go to Settings > Webhooks. See the docs for more info.

Singleton Object Type
Object Types can now be a singleton. A singleton Object Type is any type of content that only has one Object. For example Home Page, Site Settings, etc. As opposed to Blog Posts, Pages, etc. which are multiple Object Types.

API Updates
You can now get Merge Request Objects from the API to perform diffs against Objects in your target Bucket. See the docs for more info.

We hope you find these updates useful in your content workflows. It's our mission to make your use of Cosmic enjoyable and enables your team to do your best work. If you have any questions or comments, reach out to us on Twitter, and join us in Slack.

Dashboard Experience Updates

We've got some dashboard updates that should make things in your content management world a little better.

The updates include:

  1. Updated experience for selecting and reordering Object Metafields
  2. Object Type edit form updates
  3. Collapsable Metafields

Object Metafields Update
Object Metafields are a powerful tool in your Cosmic toolkit. They are used to connect Objects to create flexible content relationships. Selecting and reordering Object Metafields is now much easier thanks to a design update which includes vertical-only sorting and visible Object thumbnails. See the video below:

Object Type Form Updates
Adding and editing your Object Type content model and settings is now easier thanks in part to compressing Metafields and a new fixed save button for convenient saving.

We hope you like the new updates feature to help you use the content management dashboard with greater ease.  Please let us know if you have any questions / comments in our Slack channel, and follow us on Twitter for the latest updates to the Cosmic Headless CMS.

Introducing Merge for Environment Workflows


This feature has been upgraded into a fully-functioning feature. See Merge Requests.

We're excited to release a new feature to help you deploy content updates faster with greater peace of mind. Introducing Merge (currently in Beta), which enables your team to do quick content migrations between Buckets.

How does it work?
With the new Merge feature, you can now copy Objects between Buckets in a few clicks. In addition to our available Bucket data Import / Export, this feature allows for more granular content migrations. A great use case is when performing environment workflows.

What are Environment Workflows?
When developing any digital project, it is good practice to maintain multiple environments to allow for a streamlined quality control process (For example Development, Staging, and Production). The Merge feature fits into this workflow nicely by allowing your team to develop content in one Bucket, then after testing and approvals, Objects can be merged into another Bucket in just a few clicks.

How to use the Merge feature

  1. After logging into your Cosmic account, go to your Bucket dashboard and select any Object Type (make sure you have at least two Buckets on your account).
  2. Select the Objects you would like to merge from the Objects table
  3. From the Bulk Actions dropdown select "Merge to Another Bucket"
  4. Select the target Bucket
  5. Confirm the action by clicking the "Merge to Bucket" button

New Objects will be added, and existing Objects (with the same slug and locale) will be updated. This will also send updates to the Object Type model, Media, and connected Objects if applicable.

We hope you like the new Merge feature to help your team build content powered apps faster with more peace of mind. Merge is currently in beta and we would appreciate your feedback after testing it out in your workflows. Please let us know if you have any questions / comments in our Slack channel, and follow us on Twitter for the latest updates to the Cosmic Headless CMS.

Dashboard Updates: New Thumbnails, Search and Filter, and more

We're happy to announce some updates that will make your workflows in the Cosmic admin dashboard easier and more enjoyable. This release includes the following updates:

  1. Object thumbnails
  2. New Object Metafield selection logic
  3. Search / filter fixes
  4. Bucket thumbnail now in settings

1. Object Thumbnails
You can now add thumbnails to Objects. This gives you the ability to add visual differentiation in your Objects table. You can also select your Object thumbnail from any Image Metafield.

2. New Object Metafield Selection Logic
Before, single Object Metafields gave you the option to select Objects via a select dropdown. This made it impossible to select from an Object Type list of more than 1,000 (our API limit). Now, you can use the Select Object modal to search as well as use pagination to find your Objects. Plus you can also "Quick Add" an Object Type, which should help you create Object relationships much faster.

3. Search / Filter Fixes
You will now notice that the Search / Filter modal has been simplified and improved. Search for content quickly and easily.

4. Bucket Thumbnail
You can now edit your Bucket thumbnail from the Bucket Settings page.

We hope you enjoy these dashboard updates. Please let us know if you have any questions / comments in our Slack channel, and follow us on Twitter for the latest updates to the Cosmic Headless CMS.

Get Started with Cosmic

Build personal projects for free. Add your team at unbeatable prices.
Start Building Talk to Sales