Revisions

Learn about Revisions; the version history of content in your Cosmic Bucket.

Use the following methods to view and manage Revisions. Note: Revisions cannot be edited or deleted.

The Revision model

The Revision model contains all the information about content revisions.

Properties

Name
id
Type
string
Description
Unique identifier for Revision.
Name
object_id
Type
string
Description
ID of the Object this revision belongs to.
Name
title
Type
string
Description
Object title at time of revision.
Name
slug
Type
string
Description
Object slug at time of revision.
Name
content
Type
string
Description
HTML Content at time of revision. (deprecatated in API v3, use Metafield instead)
Name
metadata
Type
object
Description
Values of the Metafields at time of revision.
Name
created_by
Type
string
Description
The id of the user who created the revision.
Name
created_at
Type
string
Description
Date the revision was created.
Name
status
Type
enum
Description
Status of the revision.
Options published | draft
Name
published_at
Type
string
Description
Date revision was published (if applicable).
Name
modified_at
Type
string
Description
Date revision was last modified.
Name
locale
Type
string
Description
See localization for locale options.

The Revision model

{
  "id": "64fe8a1b24090e0008683e53",
  "object_id": "63dc57ca24090e0008683d42",
  "title": "Add a headless CMS to Astro in 3 easy steps",
  "slug": "add-a-headless-cms-to-astro-in-3-easy-steps",
  "bucket": "63dc24a4d71e244b63c88fca",
  "created_at": "2023-03-23T12:08:13.547Z",
  "modified_at": "2023-03-23T12:08:13.547Z",
  "status": "published",
  "thumbnail": "https://imgix.cosmicjs.com/1c8531f0-97fb-11ed-81d8-8f0123e10511-A-photo-of-Michelangelos-sculpture-of-David-wearing-headphones-djing.webp",
  "published_at": "2023-03-23T12:08:13.547Z",
  "created_by": "629e6cdda6f4f100091ae2e0",
  "type": "blog-posts",
  "metadata": {
    "content": "Astro is a lightweight web framework capable of shipping highly performant websites with minimal (or non-existent) JavaScript bundles. In this guide...",
    "image": {
      "url": "https://cdn.cosmicjs.com/02670ac0-38ef-11ed-adfd-ddb1795c6ac6-add-a-headless-cms-to-astro-in-3-easy-steps.png",
      "imgix_url": "https://imgix.cosmicjs.com/02670ac0-38ef-11ed-adfd-ddb1795c6ac6-add-a-headless-cms-to-astro-in-3-easy-steps.png"
    },
    "published_date": "2022-09-20",
    "author": {
      "title": "Bill Brasky"
    }
  }
}

GET/v3/buckets/:bucket_slug/objects/:object_id/revisions

Get Revisions

This endpoint enables you to retrieve a list of revisions for a specific Object.

Required parameters

Name
object_id
Type
string
Description
ID of the Object to retrieve revisions for.

Optional methods

Name
props
Type
string|array
Description
Declare which properties to return in comma-separated string (or array if using the NPM module). Remove to see all Revision properties.
Name
limit
Type
number
Description
Limit the number of Revisions returned.
Default 1000
Name
skip
Type
number
Description
Used for pagination. The number of Revisions to skip.
Default 0
Name
sort
Type
enum
Description
Order of Revisions returned.
Options created_at, -created_at
Use - for descending order.
Default -created_at (newest first)
Name
useCache
Type
bool
Description
Set to false for real-time updates. Increases latency of endpoint.
Default true
Name
pretty
Type
bool
Description
Set to true for reader-friendly formated JSON response.
Default false

Request

GET

/v3/buckets/:bucket_slug/objects/:object_id/revisions

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY'
})

await cosmic.objectRevisions.find('object-id').props([
  'id',
  'title',
  'created_at',
  'status'
]).limit(10)

Response

{
  "revisions": [
    {
      "id": "64fe8a1b24090e0008683e53",
      "title": "Add a headless CMS to Astro in 3 easy steps",
      "created_at": "2023-03-23T12:08:13.547Z",
      "status": "published"
    },
    {
      "id": "64fe8a0924090e0008683e52",
      "title": "Add a headless CMS to Astro in 3 easy steps (Draft)",
      "created_at": "2023-03-23T12:07:45.123Z",
      "status": "draft"
    }
  ],
  "total": 2,
  "limit": 10
}

GET/v3/buckets/:bucket_slug/objects/:object_id/revisions/:revision_id

Get a single Revision

This endpoint enables you to get a single Revision by its ID.

Required parameters

Name
object_id
Type
string
Description
ID of the Object the revision belongs to.
Name
revision_id
Type
string
Description
ID of the specific revision to retrieve.

Optional methods

Name
props
Type
string|array
Description
Declare which properties to return in comma-separated string (or array if using the NPM module). Remove to see all Revision properties.
Name
useCache
Type
bool
Description
Set to false for real-time updates. Increases latency of endpoint.
Default true
Name
pretty
Type
bool
Description
Set to true for reader-friendly formated JSON response.
Default false

Request

GET

/v3/buckets/:bucket_slug/objects/:object_id/revisions/:revision_id

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY'
})

await cosmic.objectRevisions.findOne({
  objectId: 'object-id',
  revisionId: 'revision-id'
}).props([
  'id',
  'title',
  'metadata',
  'created_at'
])

Response

{
  "revision": {
    "id": "64fe8a1b24090e0008683e53",
    "title": "Add a headless CMS to Astro in 3 easy steps",
    "created_at": "2023-03-23T12:08:13.547Z",
    "metadata": {
      "content": "Astro is a lightweight web framework capable of shipping highly performant websites with minimal (or non-existent) JavaScript bundles. In this guide...",
      "image": {
        "url": "https://cdn.cosmicjs.com/02670ac0-38ef-11ed-adfd-ddb1795c6ac6-add-a-headless-cms-to-astro-in-3-easy-steps.png",
        "imgix_url": "https://imgix.cosmicjs.com/02670ac0-38ef-11ed-adfd-ddb1795c6ac6-add-a-headless-cms-to-astro-in-3-easy-steps.png"
      },
      "published_date": "2022-09-20",
      "author": {
        "title": "Bill Brasky"
      }
    }
  }
}

POST/v3/buckets/:bucket_slug/objects/:object_id/revisions

Add a Revision

This endpoint enables you to add a new revision to an existing Object.

Adding a revision creates a new version of the Object without publishing it.

Required parameters

Name
object_id
Type
string
Description
ID of the Object to add a revision to.

Optional parameters

Name
title
Type
string
Description
Updated title for the revision.
Name
slug
Type
string
Description
Updated slug for the revision.
Name
metadata
Type
object
Description
Updated metadata values for the revision.
Name
status
Type
enum
Description
Status of the revision.
Options published | draft
Default draft
Name
trigger_webhook
Type
boolean
Description
Triggers corresponding Object action webhook (See Webhooks).

Request

POST

/v3/buckets/:bucket_slug/objects/:object_id/revisions

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY',
  writeKey: 'BUCKET_WRITE_KEY'
})

await cosmic.objectRevisions.insertOne('object-id', {
  title: 'Updated Blog Post Title',
  metadata: {
    content: 'This is the updated content for the blog post...',
    featured_post: true
  },
  status: 'draft'
})

Response

{
  "revision": {
    "id": "65fe8a1b24090e0008683e54",
    "object_id": "63dc57ca24090e0008683d42",
    "title": "Updated Blog Post Title",
    "slug": "add-a-headless-cms-to-astro-in-3-easy-steps",
    "status": "draft",
    "created_at": "2023-04-15T09:22:45.123Z",
    "created_by": "629e6cdda6f4f100091ae2e0",
    "metadata": {
      "content": "This is the updated content for the blog post...",
      "featured_post": true,
      "image": {
        "url": "https://cdn.cosmicjs.com/02670ac0-38ef-11ed-adfd-ddb1795c6ac6-add-a-headless-cms-to-astro-in-3-easy-steps.png",
        "imgix_url": "https://imgix.cosmicjs.com/02670ac0-38ef-11ed-adfd-ddb1795c6ac6-add-a-headless-cms-to-astro-in-3-easy-steps.png"
      }
    }
  }
}