SheetWordsResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kamai-io/json-schema/kamai-io-sheet-words-response-schema.json",
  "title": "SheetWordsResponse",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kamai-io-openapi.json#/components/schemas/SheetWordsResponse",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ok",
        "empty",
        "not_read",
        "unavailable",
        "rooms_unknown"
      ],
      "title": "Status",
      "description": "`ok`; `empty`: read, and nothing is printed; `not_read`: never read, so the words are unknown, not absent; `unavailable`: could not be read just now, try again; `rooms_unknown` (with `room_id` only): which words are in that room is unknown, which does NOT mean the room is empty."
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Note",
      "description": "A plain-English explanation whenever the answer is not a plain `ok`."
    },
    "frame": {
      "type": "string",
      "const": "page_fraction",
      "title": "Frame",
      "description": "Every position is a fraction (0..1) of the page, from the top-left corner.",
      "default": "page_fraction"
    },
    "page": {
      "anyOf": [
        {
          "additionalProperties": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page",
      "description": "The page's `width` and `height` in PDF points (1/72 inch)."
    },
    "ocr": {
      "anyOf": [
        {
          "$ref": "#/$defs/SheetWordsOcr"
        },
        {
          "type": "null"
        }
      ],
      "description": "How the image text was read."
    },
    "counts": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "integer"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Counts",
      "description": "Words on the whole sheet per source, before any filter."
    },
    "total": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Total",
      "description": "Words matching the filters, across all pages; `null` when unknown."
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Next Cursor",
      "description": "Pass it as `cursor` for the next page; `null` on the last page."
    },
    "words": {
      "items": {
        "$ref": "#/$defs/SheetWord"
      },
      "type": "array",
      "title": "Words",
      "description": "This page of words, in a fixed stored order."
    },
    "rooms": {
      "anyOf": [
        {
          "additionalProperties": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Rooms",
      "description": "Each `room_id` on this page mapped to the room's name."
    },
    "room_links_status": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "ok",
            "not_indexed",
            "unavailable"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Room Links Status",
      "description": "Whether words' rooms are known: `ok`; `not_indexed`: the sheet's text is not linked to rooms (not processed yet, or processed before the page size changed); `unavailable`: could not be read just now."
    }
  },
  "additionalProperties": true,
  "type": "object",
  "required": [
    "status"
  ],
  "$defs": {
    "SheetWord": {
      "properties": {
        "text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Text",
          "description": "The word as printed."
        },
        "bbox": {
          "anyOf": [
            {
              "items": {
                "type": "number"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bbox",
          "description": "Upright box around the word, [x0, y0, x1, y1] in fractions (0..1) of the page from the top-left corner."
        },
        "source": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "digital",
                "ocr",
                "ocr_bubble"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Source",
          "description": "Where the word was read: `digital` from the PDF's own text layer, `ocr` by text recognition on the image, `ocr_bubble` by a second, closer recognition pass inside a drawn tag bubble (door and window marks)."
        },
        "room_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Room Id",
          "description": "The room the word is printed in; its name is in the response's `rooms`. `null` means outside every room only when `room_links_status` is `ok`."
        },
        "room_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Room Name",
          "description": "The room's name, repeated on the word (only with `fields=...,room_name`)."
        },
        "rot": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rot",
          "description": "Reading direction in quarter turns: 0 left to right, 1 top to bottom, 2 upside down, 3 bottom to top."
        },
        "conf": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Conf",
          "description": "Recognition confidence, 0..1; always 1.0 for `digital` words."
        },
        "polygon": {
          "anyOf": [
            {
              "items": {
                "items": {
                  "type": "number"
                },
                "type": "array"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Polygon",
          "description": "The word's exact outline as [[x, y], ...] page fractions, following rotated text."
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Id",
          "description": "The word's id in the sheet's indexed text layer; `null` when the word is not in it."
        },
        "wall_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Wall Id",
          "description": "The wall the word is printed on, if any."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "title": "SheetWord",
      "description": "One word. Which keys appear is set by the `fields` parameter."
    },
    "SheetWordsOcr": {
      "properties": {
        "tiles": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Tiles",
          "description": "How many image tiles the recognition read."
        },
        "basis": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Basis",
          "description": "How the tile count was chosen, e.g. `door_frac` (sized to the drawing's doors) or `cv_ocr` (one tile, for a sheet that is not a floor plan). Informational: new values may appear."
        },
        "failed_tiles": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Failed Tiles",
          "description": "Tiles that could not be read, so their words are missing; `null` when unknown."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "title": "SheetWordsOcr"
    }
  }
}