Cosmic Logo

Revisions

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

Use the following methods to view and manage Revisions. Revisions cannot be edited, and past revisions are kept for a retention window set by your plan. See Retention below.

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"
    }
  }
}

Retention

How long past revisions are kept, by plan.

PlanRetention
Free30 days
Builder30 days
Team90 days
Business180 days
Small Workspace365 days
Large Workspace365 days
Enterprise365 days, extendable by agreement

Two revisions of every Object are never subject to retention: the most recent revision, and the most recent revision with status: 'published'. Those are the current state of the Object and what is live on your site, so retention only ever trims history. It cannot affect live or draft content, however old the Object is.

Three further things are worth knowing.

Retention is separate from access. Reading and restoring revisions in the dashboard requires the Revision History add-on. The window above applies to stored history on every plan whether or not the add-on is held, so on Free and Builder the add-on buys access rather than a longer window.

A longer window applies going forward, not retroactively. A revision's expiry is derived from its own creation time, so upgrading extends retention for revisions written afterwards and does not restore revisions that have already passed their window.

Restoring a revision creates a new one. The restored content is written as a new revision at the current time, so it starts a fresh window rather than inheriting the expiry of the revision it came from.

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"
      }
    }
  }
}