This is the official Cosmic JS JavaScript client. Use it to log in to your Cosmic JS account, manage Buckets, data, files and users within your Buckets. Includes cosmicjs.browser.min.js for easy integration in the browser.
Getting started
Go to https://www.cosmicjs.com, create an account and set up a Bucket.
Install
npm install cosmicjs
Or include in an HTML file
<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>
Usage
Authentication [View Docs]
Use your Cosmic JS 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: 'you@youremail.com',
password: 'yourpassword'
}).then(data => {
console.log(data)
}).catch(err => {
console.log(err)
})
Buckets
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 JS 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)
})
Users
Add Users [View Docs]
Add a new User to your Bucket.
const params = {
email: 'quasar@theuniverse.com',
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)
})
Object Types
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)
})
Objects
Add Object [View Docs]
Add a new Object to your Bucket.
const params = {
title: 'Cosmic JS Example',
type_slug: 'examples',
content: 'Learning the Cosmic JS API is really fun and so easy',
metafields: [
{
key: 'Headline',
type: 'text',
value: 'Learn Cosmic JS!'
},
{
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 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)
})
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)
})
Object Revisions
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)
})
Media
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)
})
Webhooks
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)
})
Extensions
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)
})