Buckets

Buckets are where you store content for your projects.

Add Bucket

title is the only required property. If no slug is present, the title will be converted to a slug (opens new window). See the table below for the other optional properties. The Bucket request matches the bucket.json file located in Your Bucket Dashboard > Import / Export.

Parameter	Required	Type	Description
title	required	String	Your Bucket title
slug		String	URL-friendly (opens new window) unique identifier
read_key		String	Restrict read access
write_key		String	Restrict write access
cluster		String	Add this Bucket to a Cluster. ID of existing Cluster
object_types		Array	Populate your Bucket with Object Types. See Object Types for model.
objects		Array	Populate your Bucket with Objects. See Objects for model.
media		Array	Populate your Bucket with Media. See Media for model.
media_folders		Array	Populate your Bucket with Media Folders. See Media for model.
webhooks		Array	Populate your Bucket with Webhooks. See Webhooks for model.
extensions		Array	Populate your Bucket with [Extensions]/docs(/extensions). See Extensions for model.

Definition

POST https://api.cosmicjs.com/v1/buckets

Example Request

curl -X POST "https://api.cosmicjs.com/v1/buckets" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"title": "My New Bucket"}'

Example Response

{
  "bucket": {
    "_id": "55b3d557df0fb1df7600004b",
    "slug": "my-new-bucket",
    "title": "My New Bucket"
  }
}

Definition

Cosmic.addBucket()

Example Request

const Cosmic = require('cosmicjs')({
  token: 'your-token-from-auth-request' // required
})
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)
})

Example Response

{
  "bucket": {
    "_id": "55b3d557df0fb1df7600004b",
    "slug": "my-new-bucket",
    "title": "My New Bucket"
  }
}

Get Buckets

Gets all Buckets connected to your account. Your authorization token in the header request is the only required property.

Definition

GET https://api.cosmicjs.com/v1/buckets

Example Request

curl "https://api.cosmicjs.com/v1/buckets" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json"
# Gets all Buckets connected to your account. Your authorization token in the header request is the only required property.

Example Response

{
  "buckets": [
    {
      "_id": "5a051c23ae05992b360005e7",
      "slug": "my-first-bucket",
      "title": "My First Bucket",
      "created_at": "2017-11-10T03:25:23.807Z",
      "modified_at": "2017-11-11T17:20:04.322Z"
    },
    {
      "_id": "5a329f6769a130011900000c",
      "slug": "my-second-bucket",
      "title": "My Second Bucket",
      "created_at": "2017-12-14T15:57:27.274Z",
      "modified_at": "2018-01-14T04:06:29.630Z"
    },
    {
      "_id": "5a329f6769a130011900000c",
      "slug": "my-third-bucket",
      "title": "My Third Bucket",
      "created_at": "2017-12-14T15:57:27.274Z",
      "modified_at": "2018-01-14T04:06:29.630Z"
    }
  ]
}

Definition

Cosmic.getBuckets()

Example Request

const Cosmic = require('cosmicjs')({
  token: 'your-token-from-auth-request' // optional
})
Cosmic.getBuckets()
.then(data => {
  console.log(data)
})
.catch(err => {
  console.log(err)
})

Example Response

{
  "buckets": [
    {
      "_id": "5a051c23ae05992b360005e7",
      "slug": "my-first-bucket",
      "title": "My First Bucket",
      "created_at": "2017-11-10T03:25:23.807Z",
      "modified_at": "2017-11-11T17:20:04.322Z"
    },
    {
      "_id": "5a329f6769a130011900000c",
      "slug": "my-second-bucket",
      "title": "My Second Bucket",
      "created_at": "2017-12-14T15:57:27.274Z",
      "modified_at": "2018-01-14T04:06:29.630Z"
    },
    {
      "_id": "5a329f6769a130011900000c",
      "slug": "my-third-bucket",
      "title": "My Third Bucket",
      "created_at": "2017-12-14T15:57:27.274Z",
      "modified_at": "2018-01-14T04:06:29.630Z"
    }
  ]
}

Connect to Bucket

For the NPM module:

Parameter	Required	Type	Description
slug	required	String	The Bucket slug
read_key		String	Restrict read access
write_key		String	Restrict write access

Example Request

curl "https://api.cosmicjs.com/v1/wedding-site"

Example Request

// 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-first-bucket',
  read_key: '',
  write_key: ''
})
const bucket2 = Cosmic.bucket({
  slug: 'my-other-bucket',
  read_key: '',
  write_key: ''
})

Get Bucket

Returns the entire Bucket including Object Types, Objects, Media and more. If you would like to restrict read access to your Bucket, you can do so in Your Bucket > Basic Settings.

Parameter	Required	Type	Description
hide_metafields		Enum	true, Hides metafields
read_key		String	Restrict read access to your Bucket

Definition

GET https://api.cosmicjs.com/v1/:bucket_slug

Example Request

curl "https://api.cosmicjs.com/v1/wedding-site"

Definition

bucket.getBucket()

Example Request

Delete Bucket

DANGER

Deletes the whole Bucket. This cannot be undone.

Parameter	Required	Type	Description
id	required	String	The Bucket id found as "_id"
token	required	String	You can only delete Buckets that you have created / own.

Definition

DELETE https://api.cosmicjs.com/v1/buckets/:bucket_id

Example Request

curl -X DELETE "https://api.cosmicjs.com/v1/buckets/:bucket_id" \
-H "Authorization: Bearer <ACCESS_TOKEN>"

Example Response

{
  "status": "200",
  "message": "Bucket deleted"
}

Definition

Cosmic.deleteBucket()

Example Request

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)
})

Example Response

{
  "status": "200",
  "message": "Bucket deleted"
}

Import Bucket

DANGER

The Bucket import method removes all current data: Object Types, Objects and Media and replaces it with new data. This cannot be undone.

The Bucket data schema matches the bucket.json file located in Your Bucket Dashboard > Import / Export.

Parameter	Required	Type	Description
object_types		Array	Populate your Bucket with Object Types. See Object Types for model.
objects		Array	Populate your Bucket with Objects. See Objects for model.
media		Array	Populate your Bucket with Media. See Media for model.
media_folders		Array	Populate your Bucket with Media Folders. See Media for model.
webhooks		Array	Populate your Bucket with Webhooks. See Webhooks for model.
extensions		Array	Populate your Bucket with Extensions. See Extensions for model.

Definition

DELETE https://api.cosmicjs.com/v1/buckets/:bucket_id

Example Request

curl -X DELETE "https://api.cosmicjs.com/v1/buckets/:bucket_id" \
-H "Authorization: Bearer <ACCESS_TOKEN>"

Example Response

{
  "status": "200",
  "message": "Bucket deleted"
}

Definition

Cosmic.importBucket()

Example Request

const Cosmic = require('cosmicjs')({
  token: 'your-token-from-auth-request' // required
})
const params = {
  "id": "5ace13795a39fb49db87ac95", // Bucket id found in Bucket Settings > Basic Settings
  "bucket": { // import data
    "object_types": [...],
    "objects": [...],
    "media": [...]
  }
}
Cosmic.importBucket(params).then(data => {
  console.log(data)
}).catch(err => {
  console.log(err)
})

Example Response

{
  "bucket": {
    "_id": "5ace13795a39fb49db87ac95",
    "slug": "same-bucket-slug",
    "title": "Same Bucket Title",
    "object_types": [...], // all new Object Types
    "objects": [...], // all new Objects
    "media": [...] // all new Media
  }
}