---
title: "Add a revision to an Object"
method: POST
path: "/buckets/{slug}/objects/{object_id}/revisions"
tags: ["Object revisions"]
---

# Add a revision to an Object

`POST /buckets/{slug}/objects/{object_id}/revisions`

Create a new revision of an Object without publishing it. The revision is created with status `draft`; publish it by updating the Object itself with `status: published`. Use this to stage an edit for review rather than changing live content.

## Request body

- RevisionCreate — Creates a draft revision. Publish by updating the Object with `status: published`.
  - `title` string
  - `slug` string
  - `status` 'published' | 'draft'
  - `content` string
  - `metadata` Metadata — Values of the Metafields defined on the Object type, keyed by Metafield `key`. The value shape follows the Metafield type, and differs between write and read for two of them: - Text, textarea, markdown, and HTML Metafields are strings. Number Metafields are numbers, switches are booleans, dates are ISO 8601 strings. - Object Relationship Metafields are written as an Object `id` string (or an array of ids for the multiple variant) and returned as a nested Object (or array of Objects) once `depth` is at least 1. - File and Image Metafields are written as a media `name` string (or an array of names) and returned as an object with `url` and `imgix_url`, plus `alt_text`, `width`, and `height` when requested via `props`. - Repeater Metafields are arrays of objects keyed by the child Metafield keys.
  - `thumbnail` string — Media `name`.
  - `locale` string
  - `publish_at` union — UNIX millisecond timestamp.
    - string
    - number
  - `unpublish_at` union — UNIX millisecond timestamp.
    - string
    - number
  - `trigger_webhook` boolean

## Response `200`

The created revision.

- RevisionResponse
  - `revision` Revision, required — An immutable snapshot of an Object at a point in time.
    - `id` string
    - `object_id` string — The Object this revision belongs to.
    - `type` string
    - `title` string
    - `slug` string
    - `status` 'published' | 'draft'
    - `content` string, nullable
    - `metadata` Metadata — Values of the Metafields defined on the Object type, keyed by Metafield `key`. The value shape follows the Metafield type, and differs between write and read for two of them: - Text, textarea, markdown, and HTML Metafields are strings. Number Metafields are numbers, switches are booleans, dates are ISO 8601 strings. - Object Relationship Metafields are written as an Object `id` string (or an array of ids for the multiple variant) and returned as a nested Object (or array of Objects) once `depth` is at least 1. - File and Image Metafields are written as a media `name` string (or an array of names) and returned as an object with `url` and `imgix_url`, plus `alt_text`, `width`, and `height` when requested via `props`. - Repeater Metafields are arrays of objects keyed by the child Metafield keys.
    - `bucket` string
    - `thumbnail` string, nullable
    - `locale` string, nullable
    - `created_at` string, date-time
    - `created_by` string
    - `modified_at` string, date-time
    - `published_at` string, date-time, nullable

## Other responses

- `400` — The request was invalid, most often a malformed `query` or a Metafield value that failed validation.
- `401` — The access key is missing or incorrect.
- `402` — The Bucket needs to be upgraded before it can be used again.
- `404` — The addressed resource does not exist in this Bucket. Note that this covers a resource missing from a route that exists; an unrecognized route answers 200 with a `Route not found` body instead, as described in the API description above.
- `429` — Too many requests hit the API too quickly. Back off and retry.
- `500` — Something went wrong on the Cosmic side.

---

[API](https://skmtc.dev/cosmicjs/apis/cosmic-rest-api-v3.md) · [All operations](https://skmtc.dev/cosmicjs/apis/cosmic-rest-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cosmicjs/cosmic-rest-api-v3/revisions/e0aa2a0913b3/schema)