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.

Parameter	Required	Type	Default	Description
read_key	required	String		Restrict read access to your Bucket
query		JSON		A JSON string to perform Object search and filtering. See Queries section for more detail.
props		String		Declare 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`
status		Enum	published	published, any (returns 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	true, Makes the response more reader-friendly
show_metafields		Enum	false	true, 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.

Parameter	Required	Type	Default	Description
read_key	required	String		Restrict read access to your Bucket
props		String		Declare which properties to return in comma-separated string. Reference full Object for all available properties. Example: `?props=id,title,metadata.author`
status		Enum	published	published, any (returns latest draft or published Object)
pretty		Enum	false	true, Makes the response more reader-friendly
show_metafields		Enum	false	true, 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.

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 Objects	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		String	Add localization to the Object
thumbnail		String	Media `name`. Media must be available in Bucket. See Media.
pretty		Enum	true, 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.

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 Objects	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.
pretty	Enum	true, 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."
}

Objects

Get Objects#

Using Props#

Get Object#

Using Props#

Add Object#

Edit Object#

Delete Object#

Get Objects

Using Props

Get Object

Using Props

Add Object

Edit Object

Delete Object