๐ View Docs
This is the official JavaScript client for the Cosmic headless CMS. Use it to log in to your Cosmic account, manage Buckets, data, files and users within your Buckets. Includes cosmicjs.browser.min.js
for easy integration in the browser.
Go to https://www.cosmicjs.com, create an account and set up a Bucket.
npm install cosmicjs
<script src="https://unpkg.com/cosmicjs@latest/cosmicjs.browser.min.js"></script>
<script>
// Exposes the global variable Cosmic
// Never expose your private keys or credentials in any public website's client-side code
</script>
Authentication [View Docs]
Use your Cosmic account email and password to create an authentication token. Authentication is only required for account-level access such as adding / removing Buckets from your account, getting user info, etc. The token is not required to query Bucket content.
const Cosmic = require('cosmicjs')() // empty init
Cosmic.authenticate({
email: '[email protected]',
password: 'yourpassword'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Add Bucket [View Docs]
Add a new Bucket to your account.
const Cosmic = require('cosmicjs')({
token: 'your-token-from-auth-request' // from Cosmic.authenticate
})
Cosmic.addBucket({
title: 'My New Bucket',
slug: 'my-new-bucket' // must be unique across all Buckets in system
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get Buckets [View Docs]
Get all Buckets connected to your account.
const Cosmic = require('cosmicjs')({
token: 'your-token-from-auth-request' // required
})
Cosmic.getBuckets().then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Connect to Bucket [View Docs]
Use the Cosmic.bucket
method to connect to different Buckets in your account. If you would like to restrict read and write access to your Bucket, you can do so in Your Bucket > Basic Settings in your Cosmic Dashboard.
// Use the Cosmic.bucket method to connect to different Buckets in your account.
const Cosmic = require('cosmicjs')({
token: 'your-token-from-auth-request' // optional
})
const bucket = Cosmic.bucket({
slug: 'my-new-bucket',
read_key: '',
write_key: ''
})
const bucket2 = Cosmic.bucket({
bucket: 'my-other-bucket',
read_key: '',
write_key: ''
})
Get Bucket [View Docs]
Returns the entire Bucket including Object Types, Objects, Media and more.
bucket.getBucket().then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Delete Bucket [View Docs]
Deletes the Bucket
const Cosmic = require('cosmicjs')({
token: 'your-token-from-auth-request' // required
})
Cosmic.deleteBucket({
id: 'bucket_id'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Add Users [View Docs]
Add a new User to your Bucket.
const params = {
email: '[email protected]',
role: 'editor',
first_name: 'Quasar',
last_name: 'Jones'
}
bucket.addUser(params).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get Users [View Docs]
Get users from your Bucket.
bucket.getUsers().then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get User [View Docs]
Get a user from your Bucket.
bucket.getUser({ id: '5357ef811693be2118000001' }).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Add Object Type [View Docs]
Add a new Object Type to your Bucket.
const params = {
title: 'Pages',
singular: 'Page',
slug: 'pages',
metafields: [
{
type: 'text',
title: 'Headline',
key: 'headline',
required: true
},
{
type: 'file',
title: 'Hero',
key: 'hero',
required: true
}
]
}
bucket.addObjectType(params).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get Object Types [View Docs]
Get all Object Types in your Bucket.
bucket.getObjectTypes().then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Edit Object Type [View Docs]
Edit an existing Object Type in your Bucket.
bucket.editObjectType({
slug: 'posts',
title: 'New Posts Title'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Delete Object Type [View Docs]
Delete an existing Object Type from your Bucket. *This does not delete Objects in this Object Type.
bucket.deleteObjectType({
slug: 'posts'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Add Object [View Docs]
Add a new Object to your Bucket.
const params = {
title: 'Cosmic Example',
type_slug: 'examples',
content: 'Learning the Cosmic API is really fun and so easy',
metafields: [
{
key: 'Headline',
type: 'text',
value: 'Learn Cosmic!'
},
{
key: 'Author',
type: 'text',
value: 'Quasar Jones'
}
],
options: {
slug_field: false
}
}
bucket.addObject(params).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get All Objects [View Docs]
Returns all Objects from your Bucket.
bucket.getObjects({
limit: 2,
props: 'slug,title,type_slug' // get only what you need
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get Objects by Type [View Docs]
Get Objects from an Object Type. Uses getObjects
method with additional type
param.
const params = {
type: 'posts',
limit: 5,
skip: 0,
props: 'slug,title,content', // get only what you need
sort: '-created_at', // optional, if sort is needed. (use one option from 'created_at,-created_at,modified_at,-modified_at,random')
locale: 'en' // optional, if localization set on Objects
status: 'all' // optional, if need to get draft Objects
}
bucket.getObjects(params).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Advanced Queries (Beta) [View Docs]
Advanced queries give you powerful NoSQL database-like functionality for content fetching. Use the query
parameter to send a valid JSON (stringified) query on the Get Objects Endpoint. View more examples in the docs.
const params = {
type: 'posts',
props: 'slug,title,content', // get only what you need
query: {
'metadata.number': {
'$gte': 3,
'$lte': 6
}
}
}
bucket.getObjects(params).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Search and Filter Objects [View Docs]
Search Objects in an Object Type. Uses getObjects
method with additional params.
// Search by keyword in title or content
const params = {
type: 'posts',
q: 'cats',
limit: 5,
skip: 0,
sort: '-created_at', // optional, if sort is needed. (use one option from 'created_at,-created_at,modified_at,-modified_at,random')
locale: 'en' // optional, if localization set on Objects,
status: 'all' // optional, if need to get draft Objects,
}
// Search by Metafield value
const params = {
type_slug: 'posts',
metafield_key: 'headline',
metafield_value: 'Hello World',
limit: 5,
skip: 0,
sort: '-created_at', // optional, if sort is needed. (use one option from 'created_at,-created_at,modified_at,-modified_at,random')
}
bucket.getObjects(params).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get Single Object [View Docs]
Returns a single Object from your Bucket.
bucket.getObject({
slug: 'home',
props: 'slug,title,content' // get only what you need
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Edit Object [View Docs]
Edit an existing Object in your Bucket.
bucket.editObject({
slug: 'cosmic-js-example',
title: 'New Title Edit'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Edit Object Metafields [View Docs]
You can edit an existing Object's Metafields by using the following method. This method allows you to edit specific Metafields identified by key
, without affecting other Metafields.
const params = {
slug: 'my-object',
metafields: [
{
title: 'Headline',
key: 'headline',
type: 'text',
value: 'What I Learned Today'
},
{
title: 'Subheadline',
key: 'subheadline',
type: 'text',
value: 'Something different'
}
]
}
const bucket = Cosmic.bucket({
slug: 'bucket-slug',
write_key: ''
})
bucket.editObjectMetafields(params)
.then(data => {
console.log(data)
})
.catch(err => {
console.log(err)
})
Delete Object [View Docs]
Delete an existing Object in your Bucket.
bucket.deleteObject({
slug: 'cosmic-js-example'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get Object Revisions [View Docs]
Returns all Object Revisions from the specified Object.
bucket.getObjectRevisions({
slug: 'a-wonderful-blog-post-about-earth',
props: 'slug,title,created_at', // get only what you need
limit: 2,
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Add Object Revision [View Docs]
Add Object Revision to an Object.
bucket.addObjectRevision({
slug: 'a-wonderful-blog-post-about-earth',
content: 'Some different content to try out',
status: 'draft'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Add Media [View Docs]
The only required post value is media which is the name of your media sent.
bucket.addMedia({
media: '<FILE_DATA>',
folder: 'your-folder-slug',
metadata: {
caption: 'Beautiful picture of the beach',
credit: 'Tyler Jackson'
}
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get Media [View Docs]
You can add the folder
parameter to get Media from a certain folder. You can use the full Imgix suite of image processing tools on the URL provided by the imgix_url
property value. Check out the Imgix documentation for more info.
bucket.getMedia({
folder: 'groomsmen',
props: 'imgix_url' // get only what you need
limit: 3
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Delete Media [View Docs]
bucket.deleteMedia({
id: '5a4b18e12fff7ec0e3c13c65'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Add Webhook [View Docs]
Sends a POST request to the endpoint of your choice when the event occurs. The data payload in the same fomat as Object and Media. Read more about Webhooks including the payload sent to the endpoint on the Webhooks documentation page.
bucket.addWebhook({
event: 'object.created.published',
endpoint: 'http://my-listener.com'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get Webhooks [View Docs]
Get webhooks in your Bucket. Authentication token is required in the header (see Authentication section). Must have admin level access.
bucket.getWebhooks()
.then(data => {
console.log(data)
})
.catch(err => {
console.log(err)
})
Delete Webhook [View Docs]
bucket.deleteWebhook({
id: 'c62defe0-5f93-11e7-8054-873245f0e98d'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Add Extension [View Docs]
Adds an Extension to your Bucket. Post values include zip
(which is the name of your file sent) or zip_url
(which is the url of the zip file) or url
(which is hosted url of extension). Note: You can only post one of these at a time. Read more about Extensions on the Extensions documentation page.
bucket.addExtension({
zip: '<ZIP_FILE_DATA>',
zip_url: '<ZIP_FILE_URL>',
url: '<EXTENSION_HOSTED_URL'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Get Extensions [View Docs]
Get Extensions in your Bucket. Authentication token is required in the header (see Authentication section). Must have admin level access.
bucket.getExtensions()
.then(data => {
console.log(data)
})
.catch(err => {
console.log(err)
})
Edit Extension [View Docs]
If a write key is enabled on the requested bucket, the parameter write_key
will need to be present. For security, query_params
values will be saved as JavaScript Web Tokens (JWT), but available in your Extension as a decoded value.
bucket.editExtension({
id: 'c62defe0-5f93-11e7-8054-873245f0e98d',
query_params: [
{
key: "some_api_account_id",
value: "someapiid12345"
},
{
key: "some_api_account_secret",
value: "supersecret12345"
}
]
})
.then(data => {
console.log(data)
})
.catch(err => {
console.log(err)
})
Delete Extension [View Docs]
bucket.deleteExtension({
id: 'c62defe0-5f93-11e7-8054-873245f0e98d'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})