Skip to content

Buckets

The following endpoints allow you to get, add, edit and delete buckets in your account.

🔑

Get your keys
Your authentication token will be required to perform the following requests.
You can get your token using the API with your email and password.

Data Model

AttributeTypeNotes
idStringUnique identifier for Bucket
slugStringUnique identifier for Bucket
titleStringBucket title
created_byStringCreator User Id
created_atStringDate created
modified_atStringDate last modified
modified_byStringLast modified User Id
api_access.read_keyStringBucket read key
api_access.write_keyStringBucket write key
thumbnailStringBucket thumbnail image

Get Buckets

Gets all Buckets connected to your account.

⚠

Required
token must be passed as Authorization Bearer in the header of the request.

ParameterTypeDefaultDescription
prettyEnumfalsetrue, Makes the response more reader-friendly

Methods

Cosmic.getBuckets()

Example Request

const Cosmic = require("cosmicjs")({
  token: "your-token-from-auth-request",
});
const data = await Cosmic.getBuckets();

Example Response

{
  "buckets": [
    {
      "id": "600af4e0c56e342a668b0d30",
      "slug": "bucket-added-from-api",
      "title": "Bucket added from API V2",
      "created_at": "2021-01-22T15:53:04.754Z",
      "modified_at": "2021-01-22T15:57:44.863Z",
      "api_access": {
        "write_key": "...",
        "read_key": "..."
      }
    }
  ]
}

Get Bucket

Returns bucket by slug connected to your Bucket.

⚠

Required
token must be passed as Authorization Bearer in the header of the request.

ParameterTypeDefaultDescription
prettyEnumfalsetrue, Makes the response more reader-friendly

Methods

Cosmic.getBucket()

Example Request

const Cosmic = require("cosmicjs")({
  token: "your-token-from-auth-request",
});
const data = await Cosmic.getBucket({ slug: "company-website" });

Example Response

{
  "bucket": {
    "id": "600af4e0c56e342a668b0d30",
    "slug": "bucket-added-from-api",
    "title": "Bucket added from API V2",
    "created_at": "2021-01-22T15:53:04.754Z",
    "modified_at": "2021-01-22T15:57:44.863Z",
    "api_access": {
      "write_key": "5WT161Y1Qd8fv6we7anNgA4X3ya5fX4EFcq7hYdV5QpC3EsHbh",
      "read_key": "O1eShESixXMMizLFEH1pg7kh4qwMWCqkccUJ7EIFSZOUy37YSW"
    }
  }
}

Add Bucket

Add a new bucket to your account.

title is the only required property. If no slug is present, the title will be converted to a slug. read_key & write_key will be auto-generated.

⚠

Required
token must be passed as Authorization Bearer in the header of the request.

ParameterRequiredTypeDescription
titlerequiredStringTitle of the bucket.
slugStringURL-friendly unique identifier
clusterStringAdd this Bucket to a Cluster. ID of existing Cluster
prettyEnumtrue, Makes the response more reader-friendly

Methods

Cosmic.addBucket()

Example Request

const Cosmic = require("cosmicjs")({
  token: "your-token-from-auth-request", // required
});
const data = await Cosmic.addBucket({
  title: "My New Bucket",
  slug: "my-new-bucket", // must be unique across all Buckets in system
});

Example Response

{
  "bucket": {
    "id": "600ef5162394f77404e0d447",
    "slug": "new-bucket",
    "title": "New Bucket",
    "created_at": "2021-01-25T16:43:02.477Z",
    "modified_at": "2021-01-25T16:43:02.477Z",
    "api_access": {
      "write_key": "xcnH0RKeKsCMdgavr6XySyiwZL36eTx2Q3gH9gER3J8QtniGuq",
      "read_key": "fE5cjxPSMDodKilD1t6gutaxDLjTVFl5XlgEIAg9IBAO2AZHlK"
    }
  }
}

Edit Bucket

Edit an existing bucket by slug in your account.

⚠

Required
token must be passed as Authorization Bearer in the header of the request and you must have admin access to perform this operation.

ParameterTypeDefaultDescription
titleStringTitle of the bucket.
thumbnailStringMedia name. Media must be available in Bucket. See Media.
reset_api_access_keysEnumfalsetrue, reset the read_key & write_key
prettyEnumfalsetrue, Makes the response more reader-friendly

Note: At least one of the Parameters is required to process the request.

Definition

PATCH /v2/buckets/${YOUR_BUCKET_SLUG}

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG} \
    -d '{"title":"New Bucket Title","reset_api_access_keys":true}' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer <TOKEN>"
    -X PATCH

Example Response

{
  "bucket": {
    "id": "600ef5162394f77404e0d447",
    "slug": "new-bucket-title",
    "title": "New Bucket Title",
    "created_at": "2021-01-25T16:43:02.477Z",
    "modified_at": "2021-01-25T16:46:53.226Z",
    "api_access": {
      "write_key": "fcVx2WoqyiIHffR8A0hEBaljT3ecrBubrYigJnDnXP8Cx6AeK7",
      "read_key": "vZ40FJ8wJzV2nhh9CEhniKpI6NtA4IP9uCUpPt8WgP2sxV4UpD"
    }
  }
}

Delete Bucket

Delete an existing bucket by slug from your account.

⚠

Required
token must be passed as Authorization Bearer in the header of the request and you must have admin access to perform this operation.

❗

Danger
Deletes the whole Bucket with objects, revisions, object types and media. This cannot be undone.

Methods

Cosmic.deleteBucket()

Example Request

const Cosmic = require("cosmicjs")({
  token: "your-token-from-auth-request", // required
});
const data = await Cosmic.deleteBucket({
  slug: "YOUR_BUCKET_SLUG",
});

Example Response

{
  "message": "Bucket with slug: '${YOUR_BUCKET_SLUG}' deleted successfully.'"
}