Skip to content

Object Revisions

The following endpoints enable you to create and read Object revisions in your Bucket. (Updating and deleting not possible.)

🔑

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/:object_id/revisions
GET /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:object_id/revisions/:revision_id
POST /v2/buckets/${YOUR_BUCKET_SLUG}/objects/:object_id/revisions

Get Object Revisions

Get Object Revisions of Object with id 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.
show_metafieldsEnumfalsetrue, Shows metafields
propsStringDeclare which properties to return in comma-separated string. Reference full Object for all available properties. Example: ?props=id,title,metadata.author
sortEnumordercreated_at, -created_at, modified_at, -modified_at, random, order
limitNumber1000The number of Objects to return
skipNumber0The number of Objects to skip
prettyEnumfalsetrue, Makes the response more reader-friendly

Definition

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

Methods

bucket.getObjectRevisions()

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.getObjectRevisions({
  id: "5ff75368c2dfa81a91695cec",
  props: "slug,title,created_at",
  limit: 10,
});

Example Response

{
  "revisions": [
    {
      "id": "5ff75368c2dfa81a91695cec",
      "slug": "title-of-the-post",
      "title": "Title of the Post",
      "content": "",
      "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",
      "object_id": "5ff75368c2dfa81a91695cec",
      "type": "posts",
      "metadata": null
    },
    {
      "id": "5ff754491a90d61b34aacdbe",
      "slug": "title-of-the-post",
      "title": "This is updated Title",
      "content": "",
      "bucket": "5f7357124b331d76c08de989",
      "created_at": "2021-01-07T18:34:49.828Z",
      "modified_at": "2021-01-07T18:34:49.828Z",
      "status": "published",
      "published_at": "2021-01-07T18:31:04.005Z",
      "object_id": "5ff75368c2dfa81a91695cec",
      "type": "posts",
      "metadata": null
    }
  ],
  "total": 4,
  "limit": 2
}

Get Object Revision

Returns a single Revision by id from your Object.

ParameterRequiredTypeDefaultDescription
read_keyrequiredStringRestrict read access to your Bucket
show_metafieldsEnumfalsetrue, Shows metafields
propsStringDeclare which properties to return in comma-separated string. Reference full Object for all available properties. Example: ?props=id,title,metadata.author
prettyEnumfalsetrue, Makes the response more reader-friendly

cURL

curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/objects/:object_id/revisions/:revision_id \
    -d read_key=${YOUR_BUCKET_READ_KEY} \
    -G

Example Response

{
  "revision": {
    "id": "5ff75368c2dfa81a91695cec",
    "slug": "title-of-the-post",
    "title": "Title of the Post",
    "content": "",
    "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",
    "object_id": "5ff75368c2dfa81a91695cec",
    "type": "posts",
    "metadata": null
  }
}

Add Object Revision

Add a new Revision to your Object.

⚠

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.

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

bucket.addObjectRevision()

Example Request

const Cosmic = require("cosmicjs");
const api = Cosmic();
const bucket = api.bucket({
  slug: "YOUR_BUCKET_SLUG",
  read_key: "YOUR_BUCKET_READ_KEY",
});
const params = {
  id: "5ff75368c2dfa81a91695cec",
  title: "New Title of the Post",
  slug: "new-title-of-the-post",
};
const data = await bucket.addObjectRevision(params);

Example Response

{
  "revision": {
    "id": "5ff75368c2dfa81a91695cec",
    "slug": "new-title-of-the-post",
    "title": "New 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"
  }
}