---
title: "Open a review room on a preview build"
method: POST
path: "/{id}/preview"
---

# Open a review room on a preview build

`POST /{id}/preview`

## Request

- Base URL: `https://marklayer.app/api`
- URL: `https://marklayer.app/api/{id}/preview`
- Auth: none declared

What the marklayer_share_preview tool calls. Creates the room at the id you chose and never overwrites one.

## Path parameters

- `id` string, required: Unguessable share id you choose — it is the access token. Creating a new one takes at least 12 characters of [A-Za-z0-9_-]; a nanoid() or uuid is ideal.

## Request body

- CreatePreview
  - `url` string, uri, required: Absolute http(s) URL of the page to review
  - `title` string, required: What this is, shown to reviewers
  - `repo` string
  - `branch` string
  - `sha` string
  - `note` string: What changed and what to look at
  - `questions` object[]: Polls to open the room with: 2–6 options each, at most 5
    - `prompt` string, required
    - `options` string[], required
  - `previous` string: A room you hold (link or id). With the same repo and branch, the new room becomes its next version. Naming it is the proof you hold it: rooms are never chained by repo and branch alone.
  - `agent` string: Who is asking, shown as the author of any polls

## Response `200`

Created

- PreviewCreated
  - `id` string, required
  - `url` string, required
  - `version` number, nullable, required
  - `previous` string, nullable, required

## Other responses

- `400`: Invalid preview
- `409`: Id already taken

---

[API](https://skmtc.dev/marklayer/apis/marklayer-share-api.md) · [All operations](https://skmtc.dev/marklayer/apis/marklayer-share-api/llms.txt) · [OpenAPI document](https://skmtc.dev/marklayer/apis/marklayer-share-api/revisions/0d8cd55afad9?raw)