---
title: "List a sheet's markups"
method: GET
path: "/v1/blueprints/{blueprint_id}/markups"
tags: ["Blueprints / Markups"]
---

# List a sheet's markups

`GET /v1/blueprints/{blueprint_id}/markups`

## Request

- Base URL: `https://api.kamai.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kamai.io/v1/blueprints/{blueprint_id}/markups`
- Auth: HTTP bearer

The sheet's markups (revision clouds, highlights and notes with an arrow), made in
the Kamai app, its chat or this API, oldest first. Markups are review marks: they are
never counted as elements or measured.

Positions are fractions of the page, `[x, y]` in 0..1 from the top-left corner: `box`
is `[x0, y0, x1, y1]`, `points` a highlight's stroke (or a cloud's outline when it is
not a box), `pointer` a note's arrow tip. `room` and `room_id` name the room a note points
at; a note the app pinned to an element carries `element` and `element_id` instead.
`version` is what an update or a delete sends back. `updated_at_max` moves on every
change, deletes included, so poll it to know when to read again.

## Path parameters

- `blueprint_id` string, required

## Response `200`

Successful Response

- MarkupListResponse
  - `blueprint_id` string, required: The sheet.
  - `name` string, required: The sheet's label, as GET /v1/projects/{id}/sheets shows it.
  - `markups` MarkupRecord[]: The sheet's live markups, oldest first.
    - `id` string, required: The markup's id.
    - `kind` 'cloud' | 'highlight' | 'note', required: `cloud`: a revision cloud; `highlight`: a marker stroke; `note`: a text box, optionally with an arrow.
    - `blueprint_id` string, required: The sheet it is drawn on.
    - `box` number[], nullable: Its bounding box, [x0, y0, x1, y1] in fractions (0..1) of the page from the top-left corner.
    - `points` array[], nullable: A highlight's stroke, or a cloud's outline when it is not a plain box, as [[x, y], ...] page fractions.
      - number[]
    - `pointer` number[], nullable: A note's arrow tip, [x, y] page fractions.
    - `text` string, nullable: The note's text.
    - `style` object: `color` (#RRGGBB), `width` and `font_size` in PDF points, `opacity` 0..1; defaults filled in.
    - `version` integer, required: Increases on every change; send it back on an update or a delete.
    - `can_edit` boolean: Whether you may change or delete it (its author or the project owner).
    - `author` string, nullable: The author's display name, or `null` when the account has none.
    - `source` 'app' | 'chat' | 'mcp', nullable: Where it was made: `app` (the Kamai app), `chat` (its assistant) or `mcp` (this API or an MCP client).
    - `created_at` string, nullable: When it was made (ISO 8601, UTC).
    - `updated_at` string, nullable: When it last changed (ISO 8601, UTC).
    - `delta` integer, nullable: A cloud's revision number, shown as Δ1, Δ2… per sheet; never reused after a delete.
    - `room` string, nullable: The room a note's arrow points at, by name.
    - `room_id` string, nullable: That room's id as `{blueprint_id}::{room id}`; the part after `::` is the room's feature `id`. Re-resolved on a list read when a room still covers the arrow tip; create/patch/delete responses carry the id from creation time.
    - `element` string, nullable: The element a note was pinned to in the app, by name (instead of `room`).
    - `element_id` string, nullable: That element's id, as the app recorded it.
    - `deleted` boolean, nullable: `true` on the record a delete returns.
  - `updated_at_max` string, nullable: The latest change on the sheet's markups, deletes included: refetch only when it moves.

## Other responses

- `404`: The sheet is not in one of your projects, or the markup is not on this sheet.
- `409`: The sheet has no page size yet (still processing), or, for a clip, its PDF is not available.
- `422`: Validation Error
- `503`: Markups are not available on this server yet.

---

[API](https://skmtc.dev/kamai/apis/kamai-api.md) · [All operations](https://skmtc.dev/kamai/apis/kamai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kamai/apis/kamai-api/revisions/78f938546270?raw)