Objects

The following endpoints enable you to create, read, update, and delete Objects in your Bucket. See API Introduction for getting started information.

🔑

Get your keys
Your Bucket slug,read_key, and write_key will be required to perform the following requests. These can be found in Bucket Settings > API Access in your Bucket Dashboard .

Endpoints


GET /v2/buckets/${YOUR_BUCKET_SLUG}/objects
POST /v2/buckets/${YOUR_BUCKET_SLUG}/objects
GET /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id
PATCH /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id
DELETE /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id
GET /v2/buckets/${YOUR_BUCKET_SLUG}/merge-requests/:id/objects

Data Model

Attribute	Type	Notes
id	String	Unique identifier for Object
slug	String	Can have multiple Objects with same slug and different locales.
type	String	Object Type slug
title	String	Object title
content	String	HTML Content
status	Enum	draft, published, defaults to published
metafields	Array of Metafields	See Metafields Model.
metadata	Object	Rendered Metafield values.
created_by	String	Author User Id
created_at	String	Date created
published_at	String	Date last published
modified_at	String	Date last modified
modified_by	String	Author User Id
publish_at	Number	UNIX millisecond timestamp. Publish automatically at a later time.
options.slug_field	Boolean	Set to false to hide the slug field
options.content_editor	Boolean	Set to false to hide the content editor
locale	Enum	See Localization for locale options.
thumbnail	String	Media `name`. Media must be available in Bucket. See Media.

Get Objects

Returns Objects in your Bucket.

Definition


GET /v2/buckets/${YOUR_BUCKET_SLUG}/objects

Parameters

Parameter	Required	Type	Default	Description
read_key	required	String		Required to read data from your Bucket
query		JSON		A JSON string to perform Object search and filtering. See Queries section for more detail. Must be URL encoded for REST requests.
props		String		Declare which properties to return in comma-separated string. Remove to see full Object and get a list of all available properties. Can include nested metadata. Example: `id,title,metadata.author.metadata.image.url`
status		Enum	published	Set to `any` for latest draft or published Object
sort		Enum	order	`created_at`, `-created_at`, `modified_at`, `-modified_at`, `random`, `order`
limit		Number	1000	The number of Objects to return
skip		Number	0	The number of Objects to skip
after		String		Objects after specified Object Id (can only use one of `skip` or `after`)
pretty		Enum	false	Set to `true` to make the response more reader-friendly
show_metafields		Enum	false	Set to `true` to show metafields
use_cache		Enum	true	Set to `false` for real-time updates. Increases latency of endpoint.

Methods

Node.js
cURL
GraphQL
CLI


bucket.getObjects()

Example Request


const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  read_key: "YOUR_BUCKET_READ_KEY",
});
const data = await bucket.getObjects({
  query: {
    type: "posts",
  },
  limit: 1,
});

Example Full Response


{
  "objects": [
    {
      "id": "5f7357967286d7773adc551e",
      "slug": "learning",
      "title": "Learning",
      "content": "<p>Learning is fun!!</p>",
      "bucket": "5f7357124b331d76c08de989",
      "created": "2020-09-29T15:49:42.005Z",
      "created_at": "2020-09-29T15:49:42.005Z",
      "modified_at": "2020-11-16T18:50:48.750Z",
      "status": "published",
      "locale": null,
      "published_at": "2020-11-16T18:50:48.750Z",
      "modified_by": "5e4d7eb92850c717ea93dba4",
      "publish_at": null,
      "unpublish_at": null,
      "type": "categories",
      "metadata": {
        "description": "This is the example description",
        "parent": {
          "id": "5f7357b27286d7773adc551f",
          "slug": "example-post",
          "title": "Example Post",
          "content": "<p>This is the post Edited!! Draft Latest</p>",
          "bucket": "5f7357124b331d76c08de989",
          "created_at": "2020-09-29T15:50:10.193Z",
          "created_by": "5e4d7eb92850c717ea93dba4",
          "modified_at": "2020-12-11T17:08:52.463Z",
          "created": "2020-09-29T15:50:10.193Z",
          "status": "published",
          "thumbnail": "",
          "published_at": "2020-12-11T16:07:10.451Z",
          "modified_by": "5e4d7eb92850c717ea93dba4",
          "publish_at": null,
          "unpublish_at": null,
          "type": "posts",
          "metadata": {
            "category": {
              "id": "5f7357967286d7773adc551e",
              "slug": "learning",
              "title": "Learning",
              "content": "<p>Learning is fun!!</p>",
              "bucket": "5f7357124b331d76c08de989",
              "created": "2020-09-29T15:49:42.005Z",
              "created_at": "2020-09-29T15:49:42.005Z",
              "modified_at": "2020-11-16T18:50:48.750Z",
              "status": "published",
              "locale": null,
              "published_at": "2020-11-16T18:50:48.750Z",
              "modified_by": "5e4d7eb92850c717ea93dba4",
              "publish_at": null,
              "unpublish_at": null,
              "type": "categories",
              "metadata": {
                "description": "This is the example description",
                "parent": "5f7357b27286d7773adc551f"
              }
            }
          }
        }
      }
    }
  ],
  "total": 6,
  "limit": 1
}

Using Props

💡

Quick Tip
Use props to limit the payload size and get only the data you need. Metadata can be nested as far as you need. There is no depth limit except to prevent infinite recursion.

Methods

Node.js
cURL
GraphQL
CLI


bucket.getObjects()

Example Request


const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  read_key: "YOUR_BUCKET_READ_KEY",
});
const props = [
  "title",
  "content",
  "metadata.parent.title",
  "metadata.parent.metadata.category.metadata.description",
];
const data = await bucket.getObjects({
  query: {
    type: "posts",
  },
  props: props.toString(),
  limit: 1,
});

Example Response with Props


{
  "objects": [
    {
      "title": "Learning",
      "content": "<p>Learning is fun!!</p>",
      "metadata": {
        "parent": {
          "title": "Example Post",
          "metadata": {
            "category": {
              "metadata": {
                "description": "This is the example description"
              }
            }
          }
        }
      }
    }
  ],
  "total": 6,
  "limit": 1
}

💡

Queries 101
Learn more about how to create powerful Object queries in the Queries and Logic section of the docs.

Get Object

Get a single Object in your Bucket. You can get the Object by its slug or ID.

Note
This method uses the Get Objects endpoint using queries and returns an array. This is because, with localization, you can have multiple Objects that use the same slug, but have different locales.

Example Request

Node.js
cURL
GraphQL
CLI


bucket.getObjects()

Example Request


const Cosmic = require("cosmicjs")(); // empty init;
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  read_key: "YOUR_BUCKET_READ_KEY",
});
const props = [
  "title",
  "content",
  "metadata.parent.title",
  "metadata.parent.metadata.category.title",
];
const data = await bucket.getObjects({
  query: {
    slug: "object-slug",
  },
  props: props.toString(),
});

Example Response with Props


{
  "objects": [
    {
      "slug": "object-slug",
      "title": "Object Slug Example",
      "metadata": {
        "description": "This is the example description",
        "parent": {
          "title": "Example Post",
          "metadata": {
            "category": {
              "title": "Learning"
            }
          }
        }
      }
    }
  ]
}

Get Object by ID

Returns a single Object in your Bucket by the Object Id.

Definition


GET /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id

Parameters

Parameter	Required	Type	Default	Description
read_key	required	String		Required to read data from your Bucket
id	required	String		Object id
props		String		Declare which properties to return in comma-separated string. Remove to see full Object and get a list of all available properties. Can include nested metadata. Example: `id,title,metadata.author.metadata.image.url`
status		Enum	published	Set to `any` for latest draft or published Object
pretty		Enum	false	Set to `true` to make the response more reader-friendly
show_metafields		Enum	false	Set to `true` to show metafields
use_cache		Enum	true	Set to `false` for real-time updates. Increases latency of endpoint.

Methods

Node.js
cURL
GraphQL
CLI


bucket.getObject()

Example Request


const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  read_key: "YOUR_BUCKET_READ_KEY",
});
const data = await bucket.getObject({
  id: "5e4d7eb92850c717ea93dba1",
});

Example Full Response


{
  "object": {
    "id": "5f7357967286d7773adc551e",
    "slug": "learning",
    "title": "Learning",
    "content": "<p>Learning is fun!!</p>",
    "bucket": "5f7357124b331d76c08de989",
    "created": "2020-09-29T15:49:42.005Z",
    "created_at": "2020-09-29T15:49:42.005Z",
    "modified_at": "2020-11-16T18:50:48.750Z",
    "status": "published",
    "locale": null,
    "published_at": "2020-11-16T18:50:48.750Z",
    "modified_by": "5e4d7eb92850c717ea93dba4",
    "publish_at": null,
    "unpublish_at": null,
    "type": "categories",
    "metadata": {
      "description": "This is the example description",
      "parent": {
        "id": "5f7357b27286d7773adc551f",
        "slug": "example-post",
        "title": "Example Post",
        "content": "<p>This is the post Edited!! Draft Latest</p>",
        "bucket": "5f7357124b331d76c08de989",
        "created_at": "2020-09-29T15:50:10.193Z",
        "created_by": "5e4d7eb92850c717ea93dba4",
        "modified_at": "2020-12-11T17:08:52.463Z",
        "created": "2020-09-29T15:50:10.193Z",
        "status": "published",
        "thumbnail": "",
        "published_at": "2020-12-11T16:07:10.451Z",
        "modified_by": "5e4d7eb92850c717ea93dba4",
        "publish_at": null,
        "unpublish_at": null,
        "type": "posts",
        "metadata": {
          "category": {
            "id": "5f7357967286d7773adc551e",
            "slug": "learning",
            "title": "Learning",
            "content": "<p>Learning is fun!!</p>",
            "bucket": "5f7357124b331d76c08de989",
            "created": "2020-09-29T15:49:42.005Z",
            "created_at": "2020-09-29T15:49:42.005Z",
            "modified_at": "2020-11-16T18:50:48.750Z",
            "status": "published",
            "locale": null,
            "published_at": "2020-11-16T18:50:48.750Z",
            "modified_by": "5e4d7eb92850c717ea93dba4",
            "publish_at": null,
            "unpublish_at": null,
            "type": "categories",
            "metadata": {
              "description": "This is the example description",
              "parent": "5f7357b27286d7773adc551f"
            }
          }
        }
      }
    }
  }
}

Using Props

💡

Quick Tip
Use props to limit the payload size and get only the data you need. Metadata can be nested as far as you need. There is no depth limit except to prevent infinite recursion.

Methods

Node.js
cURL
GraphQL
CLI


bucket.getObject()

Example Request


const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  read_key: "YOUR_BUCKET_READ_KEY",
});
const props = [
  "title",
  "content",
  "metadata.parent.title",
  "metadata.parent.metadata.category.title",
];
const data = await bucket.getObject({
  id: "5e4d7eb92850c717ea93dba1",
  props: props.toString(),
});

Example Response with Props


{
  "object": {
    "title": "Learning",
    "metadata": {
      "description": "This is the example description",
      "parent": {
        "title": "Example Post",
        "metadata": {
          "category": {
            "title": "Learning"
          }
        }
      }
    }
  }
}

Add Object

Creates a new Object in your Bucket.

Definition


POST /v2/buckets/${YOUR_BUCKET_SLUG}/objects

⚠

Required
Your Bucket write_key must be passed as Authorization Bearer in the header of the request. This can be found in Bucket Settings > API Access in your Admin Dashboard.

Parameters

Parameter	Required	Type	Description
type	required	String	Add Object to Object Type
title	required	String	Your Object title
slug		String	Unique identifier for your Object
content		String	Add Content to your Object
status		Enum	draft, published, defaults to published
metafields		Array of Metafields	Add Metafields to your Object. See Metafields Model.
created_by		String	Author User Id
publish_at		Number	UNIX millisecond timestamp. Publish automatically at a later time.
options.slug_field		Boolean	Set to false to hide the slug field
options.content_editor		Boolean	Set to false to hide the content editor
locale		Enum	Adds localization to the Object. See Localization for locale options.
thumbnail		String	Media `name`. Media must be available in Bucket. See Media.
trigger_webhook		Boolean	Triggers corresponding Object action Webhook (See Webhooks).
pretty		Enum	true, Makes the response more reader-friendly

Methods

Node.js
cURL
GraphQL
CLI


bucket.addObject()

Example Request


const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  write_key: "YOUR_BUCKET_WRITE_KEY",
});
const params = {
  title: "Cosmic Example",
  type: "examples",
  content: "Learning the Cosmic API is really fun and so easy",
  metafields: [
    {
      title: "Headline",
      key: "headline",
      type: "text",
      value: "Learn Cosmic!",
    },
    {
      title: "Author",
      key: "author",
      type: "text",
      value: "Quasar Jones",
    },
  ],
  options: {
    slug_field: false,
  },
};
const data = await bucket.addObject(params);

Example Response


{
  "object": {
    "id": "5ff75368c2dfa81a91695cec",
    "slug": "title-of-the-post",
    "title": "Title of the Post",
    "content": "",
    "metafields": [],
    "bucket": "5f7357124b331d76c08de989",
    "created_at": "2021-01-07T18:31:04.005Z",
    "modified_at": "2021-01-07T18:31:04.005Z",
    "status": "published",
    "published_at": "2021-01-07T18:31:04.005Z",
    "type": "posts"
  }
}

Edit Object

Edits an Object in your Bucket.

Definition


PATCH /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id

⚠

Required
Your Bucket write_key must be passed as Authorization Bearer in the header of the request. This can be found in Bucket Settings > API Access in your Admin Dashboard.

Parameters

Parameter	Type	Description
title	String	Your Object title
slug	String	Unique identifier for your Object
content	String	Add Content to your Object
status	Enum	draft, published, defaults to published
metafields	Array of Metafields	Add Metafields to your Object. See Metafields Model.
publish_at	Number	UNIX millisecond timestamp. Publish automatically at a later time.
options.slug_field	Boolean	Set to false to hide the slug field
options.content_editor	Boolean	Set to false to hide the content editor
locale	String	Add localization to the Object
thumbnail	String	Media `name`. Media must be available in Bucket. See Media.
trigger_webhook	Boolean	Triggers corresponding Object action Webhook (See Webhooks).
pretty	Enum	true, Makes the response more reader-friendly

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

Methods

Node.js
cURL
GraphQL
CLI


bucket.editObject()

Example Request


const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  write_key: "YOUR_BUCKET_WRITE_KEY",
});
const data = await bucket.editObject({
  id: "5ff75368c2dfa81a91695cec",
  title: "New Title Edit",
});

Example Response


{
  "object": {
    "id": "5ff75368c2dfa81a91695cec",
    "slug": "title-of-the-post",
    "title": "New Title Edit",
    "content": "",
    "metafields": [],
    "bucket": "5f7357124b331d76c08de989",
    "created_at": "2021-01-07T18:31:04.005Z",
    "modified_at": "2021-01-07T18:38:12.124Z",
    "status": "published",
    "published_at": "2021-01-07T18:31:04.005Z",
    "type": "posts"
  }
}

Delete Object

Deletes an Object in your Bucket. This cannot be undone.

Definition


DELETE /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:id

⚠

Required
Your Bucket write_key must be passed as Authorization Bearer in the header of the request. This can be found in Bucket Settings > API Access in your Admin Dashboard.

Parameters

Parameter	Type	Description
trigger_webhook	Boolean	Triggers corresponding Object action Webhook (See Webhooks).

Methods

Node.js
cURL
GraphQL
CLI


bucket.deleteObject()

Example Request


const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  write_key: "YOUR_BUCKET_WRITE_KEY",
});
const data = await bucket.deleteObject({
  id: "5ff75368c2dfa81a91695cec",
});

Example Response


{
  "message": "Object with id ':id' deleted successfully from bucket."
}

Get Merge Request Objects

Returns Objects included in a Merge Request. See Objects for available params.

Definition


GET /v2/buckets/${YOUR_BUCKET_SLUG}/merge-requests/:id/objects

Methods

Node.js
cURL
GraphQL
CLI


bucket.getMergeRequestObjects()

Example Request


const Cosmic = require("cosmicjs")(); // empty init
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
  read_key: "YOUR_BUCKET_READ_KEY",
});
const query = {
  slug: "new-post-in-merge-request",
  locale: "en",
};
const data = await bucket.getMergeRequestObjects({
  id: "merge-request-id",
  query,
  props: "slug,title",
});

Example Response


{
  "objects": [
    {
      "slug": "new-post-in-merge-request",
      "title": "New Post in Merge Request"
    }
  ]
}