Blueprints / Markups

Change a markup

Move, reshape, restyle or retext a markup: send version and only what changes (box, points, pointer, text, style). Moving a note's box keeps its arrow on the same spot. Answers the markup with its new version.

version must be the one last read: otherwise 409, with the markup as it is now in current, and nothing is written. Only the markup's author or the project owner can change it (403). 422 for an empty change or a shape the kind does not take.

patch/v1/blueprints/{blueprint_id}/markups/{markup_id}

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/{markup_id}
  • Auth: HTTP bearer

Path parameters

blueprint_idstring required
markup_idstring required

Request body

versioninteger required

The markup's version as last read; a newer one answers conflict.

boxnumber[] nullable

A new box, [x0, y0, x1, y1] fractions of the page (clouds and notes).

pointernumber[] nullable

A note's new arrow tip, [x, y] fractions of the page; the room under it is recorded again.

textstring nullable

New text, up to 2,000 characters; a note's cannot be empty.

styleobject nullable

Style keys to change (color, width, opacity, font_size); the others are kept.

Response

Successful Response

idstring 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_idstring required

The sheet it is drawn on.

boxnumber[] nullable

Its bounding box, [x0, y0, x1, y1] in fractions (0..1) of the page from the top-left corner.

pointernumber[] nullable

A note's arrow tip, [x, y] page fractions.

textstring nullable

The note's text.

styleobject

color (#RRGGBB), width and font_size in PDF points, opacity 0..1; defaults filled in.

versioninteger required

Increases on every change; send it back on an update or a delete.

can_editboolean

Whether you may change or delete it (its author or the project owner).

authorstring 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_atstring nullable

When it was made (ISO 8601, UTC).

updated_atstring nullable

When it last changed (ISO 8601, UTC).

deltainteger nullable

A cloud's revision number, shown as Δ1, Δ2… per sheet; never reused after a delete.

roomstring nullable

The room a note's arrow points at, by name.

room_idstring 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.

elementstring nullable

The element a note was pinned to in the app, by name (instead of room).

element_idstring nullable

That element's id, as the app recorded it.

deletedboolean nullable

true on the record a delete returns.

Changes

No recorded changes to this operation across all 1 revision of this API.