Skip to content

Objects

The following endpoints allow you to get, add, edit and delete Objects in your Bucket. See API Introduction for getting started information.

Quick Tip
Your read and write keys will be required to perform the following requests. These can be found in Your Bucket > Settings > API Access in your Bucket Dashboard .

Get Objects

Get Objects in your Bucket.

ParameterRequiredTypeDefaultDescription
read_keyrequiredStringRequired to read data from your Bucket
queryJSONA JSON string to perform Object search and filtering. See Queries section for more detail.
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

const query = {
type: "posts",
};

Endpoint

GET $BASE_URL/buckets/${bucket_slug}/objects?query=${query}&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.

Example Request with Props

const query = {
type: "posts",
};
const props = `
title,
content,
metadata.parent.title,
metadata.parent.metadata.category.metadata.description
`;

Endpoint

GET $BASE_URL/buckets/${bucket_slug}/objects?query=${query}&props=${props}&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
}

Get Object

Returns a single Object by id from your Bucket.

ParameterRequiredTypeDefaultDescription
read_keyrequiredStringRequired to read data from your Bucket
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

GET $BASE_URL/buckets/${bucket_slug}/objects/${object_id}

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.

Example Request with Props

const props = `
title,
metadata.description,
metadata.parent.title,
metadata.parent.metadata.category.title
`;
GET $BASE_URL/buckets/${bucket_slug}/objects/${object_id}?props=${props}

Example Response with Props

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

Add Object

Add a new Object to your Bucket.

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

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 ObjectsAdd 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
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

Methods

POST $BASE_URL/buckets/${bucket_slug}/objects

Header

{
"Authorization": "Bearer n5MbD59UPBoVpyqi6B6DnOzAvZ..."
}

Example Body (JSON)

{
"title": "Title of the Post",
"type": "posts"
}

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

Edit an existing Object by id in your Bucket.

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

ParameterTypeDescription
titleStringYour Object title
slugStringUnique identifier for your Object
contentStringAdd Content to your Object
statusEnumdraft, published, defaults to published
metafieldsArray of ObjectsAdd 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

PATCH $BASE_URL/buckets/${bucket_slug}/objects/${object_id}

Header

{
"Authorization": "Bearer n5MbD59UPBoVpyqi6B6DnOzAvZ..."
}

Example Body (JSON)

{
"title": "This is the updated Title"
}

Example Response

{
"object": {
"id": "5ff75368c2dfa81a91695cec",
"slug": "title-of-the-post",
"title": "This is the updated Title",
"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

Delete an existing Object by id from your Bucket.

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

Query ParameterTypeDescription
trigger_webhookBooleanTriggers corresponding Object action Webhook (See Webhooks).

Methods

DELETE $BASE_URL/buckets/${bucket_slug}/objects/${object_id}?trigger_webhook=true

Header

{
"Authorization": "Bearer n5MbD59UPBoVpyqi6B6DnOzAvZ..."
}

Example Response

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

Get Merge Request Objects

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

Methods

const query = {
slug: "new-post-in-merge-request",
locale: "en"
};

Endpoint

GET $BASE_URL/buckets/${bucket_slug}/merge-requests/${merge_request_id}/objects?query=${query}&props=title,slug

Example Response

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