Skip to content

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

AttributeTypeNotes
idStringUnique identifier for Object
slugStringCan have multiple Objects with same slug and different locales.
typeStringObject Type slug
titleStringObject title
contentStringHTML Content
statusEnumdraft, published, defaults to published
metafieldsArray of MetafieldsSee Metafields Model.
metadataObjectRendered Metafield values.
created_byStringAuthor User Id
created_atStringDate created
published_atStringDate last published
modified_atStringDate last modified
modified_byStringAuthor User Id
publish_atNumberUNIX millisecond timestamp. Publish automatically at a later time.
options.slug_fieldBooleanSet to false to hide the slug field
options.content_editorBooleanSet to false to hide the content editor
localeEnumSee Localization for locale options.
thumbnailStringMedia 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

ParameterRequiredTypeDefaultDescription
read_keyrequiredStringRequired to read data from your Bucket
queryJSONA JSON string to perform Object search and filtering. See Queries section for more detail. Must be URL encoded for REST requests.
propsStringDeclare 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
statusEnumpublishedSet to any for latest draft or published Object
sortEnumordercreated_at, -created_at, modified_at, -modified_at, random, order
limitNumber1000The number of Objects to return
skipNumber0The number of Objects to skip
afterStringObjects after specified Object Id (can only use one of skip or after)
prettyEnumfalseSet to true to make the response more reader-friendly
show_metafieldsEnumfalseSet to true to show metafields
use_cacheEnumtrueSet to false for real-time updates. Increases latency of endpoint.

Methods

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

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.

Get Object by slug

✅

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

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

ParameterRequiredTypeDefaultDescription
read_keyrequiredStringRequired to read data from your Bucket
idrequiredStringObject id
propsStringDeclare 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
statusEnumpublishedSet to any for latest draft or published Object
prettyEnumfalseSet to true to make the response more reader-friendly
show_metafieldsEnumfalseSet to true to show metafields
use_cacheEnumtrueSet to false for real-time updates. Increases latency of endpoint.

Methods

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

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

ParameterRequiredTypeDescription
typerequiredStringAdd Object to Object Type
titlerequiredStringYour Object title
slugStringUnique identifier for your Object
contentStringAdd Content to your Object
statusEnumdraft, published, defaults to published
metafieldsArray of MetafieldsAdd Metafields to your Object. See Metafields Model.
created_byStringAuthor User Id
publish_atNumberUNIX millisecond timestamp. Publish automatically at a later time.
options.slug_fieldBooleanSet to false to hide the slug field
options.content_editorBooleanSet to false to hide the content editor
localeEnumAdds localization to the Object. See Localization for locale options.
thumbnailStringMedia name. Media must be available in Bucket. See Media.
trigger_webhookBooleanTriggers corresponding Object action Webhook (See Webhooks).
prettyEnumtrue, Makes the response more reader-friendly

Methods

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

ParameterTypeDescription
titleStringYour Object title
slugStringUnique identifier for your Object
contentStringAdd Content to your Object
statusEnumdraft, published, defaults to published
metafieldsArray of MetafieldsAdd Metafields to your Object. See Metafields Model.
publish_atNumberUNIX millisecond timestamp. Publish automatically at a later time.
options.slug_fieldBooleanSet to false to hide the slug field
options.content_editorBooleanSet to false to hide the content editor
localeStringAdd localization to the Object
thumbnailStringMedia name. Media must be available in Bucket. See Media.
trigger_webhookBooleanTriggers corresponding Object action Webhook (See Webhooks).
prettyEnumtrue, Makes the response more reader-friendly

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

Methods

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

ParameterTypeDescription
trigger_webhookBooleanTriggers corresponding Object action Webhook (See Webhooks).

Methods

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

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"
}
]
}