Cosmic Changelog

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

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.

Introducing New Bulk Actions

We are excited to announce a big release that enables you to effortlessly perform new bulk actions from your Cosmic admin dashboard, giving your team even greater content ops superpowers.

Bulk Edits and Search and Replace are two separate features that provide your team with huge time-savings when you need to make changes affecting multiple Objects. Let's look at what each feature does and how to use them...

What are Bulk Edits?Bulk Edit Dropdown

Bulk Edits allow you to edit fields across multiple Objects in your Bucket. For example, editing a Metafield to the same value across multiple Blog Posts used to require you to manually edit the value in every Object. Now, with Bulk Edits, you can do this in a single action saving you minutes of manual work (or hours, or more!).

How to use Bulk Edits

To use the Bulk Edits feature:

  1. Log into your Cosmic account.
  2. Select your Bucket.
  3. Go to your Objects table view by selecting any Object Type in the left-hand side nav.
  4. Use the left-side checkbox next to each Object to select which Objects to perform the action on.
  5. Click the "Bulk Edit Objects" option from the "Bulk Actions" dropdown at the top of the table.
  6. Select the fields you want to affect, add your new values, and click "Confirm".

You can currently perform bulk edits on Object content and select Metafield values.

See the video for steps:

What is Search and Replace?
Search Replace Dropdown

The Search and Replace bulk action enables you to search and replace text across Objects. For example, if you needed to replace an old link with a new link across multiple Objects and fields, you can now use the Search and Replace bulk action to do this in a single action within seconds. Before you would have had to manually edit each Object which could have taken minutes (or hours, or more!).

How to use Search and Replace

To use the Search and Replace feature:

  1. Log into your Cosmic account.
  2. Select your Bucket.
  3. Go to your Objects table view by selecting any Object Type in the left-hand side nav.
  4. Use the left-side checkbox next to each Object to select which Objects to perform the action on.
  5. Click the "Search and Replace" option from the "Bulk Actions" dropdown at the top of the table.
  6. Add the term to search for (case sensitive) and the term that will replace it.
  7. Select the fields to perform the action on. Click "Confirm".

You can currently perform search and replace on Object title, content, and select Metafield values.

See the video for steps:

Bulk Edits and Search and Replace are two new tools in your Cosmic toolbox to help you achieve the same goal: saving time!

We hope you enjoy using the new bulk actions. 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.

Webhook triggers via API, NPM modules updates, and more

We have a few exciting updates to help you power content for your modern websites and apps using Cosmic.

1. Trigger webhooks via API
You can now trigger webhooks using the API by passing trigger_webhook=true in the request body. Find your webhooks in Bucket Settings > Webhooks. Be sure to check out the Webhooks documentation and API documentation to see with which API requests this is possible (Add, Edit, and Delete Objects and Media).

2. Edit Object via API using id
We have added the functionality to edit Objects via the API using id.  Which gives you the ability to edit the Object slug (which was previously not possible). Be sure to check this out in our Edit Object API documentation.

3. Cosmic NPM module updates
Check out the latest release of Cosmic NPM module. The new version includes the following updates: 

  • Performance updates (up to 10x faster install!)
  • Codebase improvements (Refactoring and modularization)
  • Babel and webpack version bump
  • Production packages/dependencies shrink down

This update will improve the overall developer experience as well as you'll able to deliver content to users much faster 🚀. 

4. Cosmic Gatsby source plugin updates
We've updated the packages/dependencies in the Gatsby source plugin for Cosmic and fixed localMedia bugs related to Object & Objects metafields. Check out the latest version here.

We hope you enjoy these updates. If you have any questions, join our Slack community and reach out to us on Twitter.

Introducing Advanced Queries

We are excited to announce the release of Advanced Queries (Beta) now available for all accounts. This is huge for teams that would like to use Cosmic beyond basic content management, enabling laser-focused logic to deliver content.

How it works
Advanced queries give you powerful NoSQL database-like functionality for data fetching. Using the Cosmic REST API endpoint and available clients (including the Cosmic GraphQL API) you can customize your NoSQL-style query (in JSON format) to customize selectors and query logic. See below examples and the docs for more info.


To keep things concise, use the following bucket variable for the following examples.

const bucket = Cosmic.bucket({
  slug: 'bucket-slug',
  read_key: "your-read-key-found-in-bucket-settings"

Match Objects with exact title

  type: 'posts',
  props: 'slug,title,content',
  query: {
    "title": "Post 1"

Match Objects greater than or equal to metadata value

  type: 'posts',
  props: 'slug,title,content',
  query: {
    "metadata.price": {
      "$gte": 9.99

Match Objects with nested JSON metadata value (JSON Metafield)

  type: 'posts',
  props: 'slug,title,content',
  query: {
    "metadata.json_data": {
      "is_awesome": true,
      "other_data": {
        "nested": "yep"

Match Objects with any metadata values

  type: 'posts',
  props: 'slug,title,content',
  query: {
    "$or": [
         "metadata.grade": "A"
        "metadata.grade": "B"

Match Objects with string in content using a regular expression. Case insensitive with $options.

  type: 'posts',
  props: 'slug,title,content',
  query: {
    "content": {
      "$regex": "jamstack",
      "$options": "i"

Match Objects with any Multiple Object Metafield values

  type: 'posts',
  props: 'slug,title,content',
  query: {
    "metadata.categories": {
      "$in": ["category_id-1","category_id-2"]

Match Objects that don't have any Multiple Object Metafield values

  type: 'posts',
  props: 'slug,title,content',
  query: {
    "metadata.categories": {
      "$nin": ["category_id-1","category_id-2"]

See the docs for the full list of query selectors and logic operators.

Advanced Queries in the GraphQL API
You may need to set the variable outside of the main query area. Add something like this to the Query Variables area:

  "query": {
    "title": {
      "$regex": "another",
      "$options": "i"

View full screen  

We hope you enjoy using Advanced Queries to give you more power and flexibility to get your Cosmic content. This is a Beta release and we would like your feedback as we improve this feature, so please let us know what you think! Reach out to us on Twitter and join the conversation in Slack.

Get Started with Cosmic

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