Getting Started

Get started quickly adding Cosmic-powered content to your websites and apps.

Speaking Cosmic

What is a Bucket?

A Bucket is the main piece in the Cosmic content structure. It's very flexible and can power the content for an entire website or a portion of a website. Since your Bucket content is delivered via an API endpoint, your Bucket can also power content for any application including iOS, Android, tvOS, Apple Watch, IOT, AR/VR or any other way that you would like to distribute your content. You may need multiple Buckets for different environments (for example one Bucket for Staging, one Bucket for Production, etc).

What is an Object Type?

An Object Type is any collection of Objects that share a similar function. Pages, articles, projects, etc.

What is an Object?

An Object can be a page, a blog post, or anything you want it to be. Cosmic gives you the freedom to create and manage content openly and create your own data structure. Each Object allows for the creation of a title, slug, content and Metafields.

What are Metafields?

Metafields are very powerful pieces of custom data. Current available Metafield types include: text, textarea, HTML textarea, select dropown, image / file upload, date, single Object relationship, multiple Object relationship, radio buttons, check boxes, markdown, parent with nested children, repeater, and JSON. Your created Metafields are transformed into key/values stored as Metadata in the API endpoints.

Current Metafield Options


Install the Cosmic NPM module to integrate content into any new or existing website or app.

There are Node.js, React, Vue, Gatsby, Angular, and Serverless starter apps to help you get your project started quickly.

npm i -g cosmic-cli
cosmic init node-starter
cd node-starter
cosmic start


Cosmic has client libraries to help you easily manage content on your website or app. Below are a few examples of how these client libraries can be used to add dynamic content to your app without much custom coding.

Node.js Example

Install the Official Cosmic JavaScript Client on NPM.

npm i cosmicjs

Then get your content:

Browser Example

Use the Unpkg hosted browser file or add the cosmicjs.browser.min.js file from the Official Cosmic JavaScript Client on GitHub to your app. Here is a real working example application:

React Example

Edit nextjs-cms-example

Cosmic CLI

Use the Cosmic CLI to communicate directly with your Cosmic account via the command line. Below are a few quick examples.

Install the CLI globally:

npm i -g cosmic-cli

View all available commands:


Log in to your Cosmic account:

$ cosmic login
  ? Email:
  ? Password: [hidden]

Connect to a Bucket:

cosmic use-bucket simple-react-blog

Get Objects from the connected Bucket:

$ cosmic get-objects --limit 1
{ objects: 
    [ { _id: '59df6dd5fd8d731b2100118d',
        bucket: '59df6dcbfd8d731b21001188',
        slug: 'jane-doe',
        title: 'Jane Doe',
        content: '

Something about Jane...

', metafields: [Array], type_slug: 'authors', created: '2017-10-12T13:27:49.663Z', created_at: '2017-10-12T13:27:49.663Z', status: 'published', metadata: [Object] } ], limit: 1 }

Go to the Cosmic CLI NPM module page to see more examples.

Python Example

Download the Cosmic Python Client on GitHub.

git clone
cd cosmicjs-python
python install


from pythoncosmicjs import Api
# Configure
api = Api(bucket='astral', read_key='read_key', write_key='write_key')
# Get all contents of bucket including objects and media
# Get all objects
print(api.objects(limit=10, skip=5)) # limit, skip the default is None
# Get objects by type
print(api.object_type(type_slug='pages', limit=10, skip=5)) # limit, skip the default is None
# Get object
print(api.object(object_slug='object-slug')) # object_slug mandatory variable
# Get media
print(, skip=5)) # limit, skip the default is None
# Add object
print(api.add_object(title='object title', content='object content')) # title, content required variables
# Edit object
print(api.edit_object(object_slug='object-slug', title='change to the title', content='change to the content')) # title, content required variables
# Delete object
print(api.delete_object(object_slug='object-slug')) # the name of the object you want to delete
# Search object
print(api.search_object(object_type='', limit=1, skip=10, metafield_keys='bob', metafield_value='bob'))
PHP Example

Add the cosmicjs.php file from the Official Cosmic PHP Client on GitHub to your app.

git clone

Then get your content:

// in your PHP file
$config = new stdClass();
$config->bucket_slug = "astral";
$objects = $cosmicjs->getObjects();
Simple Curl


Go to the documentation to see more ways to add the power of Cosmic to your websites and applications.

Ready to Get Started?

Build personal projects for free. Add your team at unbeatable prices.
Start Now Contact Sales