Skip to content

Objects

The following endpoints allow you to get, add, edit and delete Objects in your Bucket.

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_keyrequiredStringRestrict read access to 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. Reference full Object for all available properties. Can include nested metadata. Example: ?props=id,title,metadata.author.metadata.image.url
statusEnumpublishedpublished, any (returns 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)
prettyEnumfalsetrue, Makes the response more reader-friendly
show_metafieldsEnumfalsetrue, Shows metafields

Definition

const query = {
type: "posts",
};
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.

Example Request with Props

const query = {
type: "posts",
};
const props = `
title,
content,
metadata.parent.title,
metadata.parent.metadata.category.metadata.description
`;
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_keyrequiredStringRestrict read access to your Bucket
propsStringDeclare which properties to return in comma-separated string. Reference full Object for all available properties. Example: ?props=id,title,metadata.author
statusEnumpublishedpublished, any (returns latest draft or published Object)
prettyEnumfalsetrue, Makes the response more reader-friendly
show_metafieldsEnumfalsetrue, Shows metafields

Definition

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.

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.
prettyEnumtrue, Makes the response more reader-friendly

Definition

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

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.
prettyEnumtrue, Makes the response more reader-friendly

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

Definition

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

Example Body (JSON)

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

Example Response

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

Definition

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

Example Response

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