MarkupRecord

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kamai-io/json-schema/kamai-io-markup-record-schema.json",
  "title": "MarkupRecord",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kamai-io-openapi.json#/components/schemas/MarkupRecord",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "The markup's id."
    },
    "kind": {
      "type": "string",
      "enum": [
        "cloud",
        "highlight",
        "note"
      ],
      "title": "Kind",
      "description": "`cloud`: a revision cloud; `highlight`: a marker stroke; `note`: a text box, optionally with an arrow."
    },
    "blueprint_id": {
      "type": "string",
      "title": "Blueprint Id",
      "description": "The sheet it is drawn on."
    },
    "box": {
      "anyOf": [
        {
          "items": {
            "type": "number"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Box",
      "description": "Its bounding box, [x0, y0, x1, y1] in fractions (0..1) of the page from the top-left corner."
    },
    "points": {
      "anyOf": [
        {
          "items": {
            "items": {
              "type": "number"
            },
            "type": "array"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Points",
      "description": "A highlight's stroke, or a cloud's outline when it is not a plain box, as [[x, y], ...] page fractions."
    },
    "pointer": {
      "anyOf": [
        {
          "items": {
            "type": "number"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Pointer",
      "description": "A note's arrow tip, [x, y] page fractions."
    },
    "text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Text",
      "description": "The note's text."
    },
    "style": {
      "additionalProperties": true,
      "type": "object",
      "title": "Style",
      "description": "`color` (#RRGGBB), `width` and `font_size` in PDF points, `opacity` 0..1; defaults filled in."
    },
    "version": {
      "type": "integer",
      "title": "Version",
      "description": "Increases on every change; send it back on an update or a delete."
    },
    "can_edit": {
      "type": "boolean",
      "title": "Can Edit",
      "description": "Whether you may change or delete it (its author or the project owner).",
      "default": false
    },
    "author": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Author",
      "description": "The author's display name, or `null` when the account has none."
    },
    "source": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "app",
            "chat",
            "mcp"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Source",
      "description": "Where it was made: `app` (the Kamai app), `chat` (its assistant) or `mcp` (this API or an MCP client)."
    },
    "created_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Created At",
      "description": "When it was made (ISO 8601, UTC)."
    },
    "updated_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Updated At",
      "description": "When it last changed (ISO 8601, UTC)."
    },
    "delta": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Delta",
      "description": "A cloud's revision number, shown as Δ1, Δ2… per sheet; never reused after a delete."
    },
    "room": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Room",
      "description": "The room a note's arrow points at, or the room an app-drawn cloud or highlight was linked to, by name."
    },
    "room_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Room Id",
      "description": "That room's id as `{blueprint_id}::{room id}`; the part after `::` is the room's feature `id`. Re-resolved on a read when a room still covers the linked spot. Moving a note's arrow tip, or moving or reshaping a linked cloud or highlight, re-links it at the new spot, and the update response carries it."
    },
    "element": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Element",
      "description": "The element a note was pinned to in the app, by name (instead of `room`)."
    },
    "element_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Element Id",
      "description": "That element's id, as the app recorded it."
    },
    "deleted": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Deleted",
      "description": "`true` on the record a delete returns."
    }
  },
  "additionalProperties": true,
  "type": "object",
  "required": [
    "id",
    "kind",
    "blueprint_id",
    "version"
  ]
}