--- title: "List the words printed on a sheet" method: GET path: "/v1/blueprints/{blueprint_id}/words" tags: ["Blueprints / Drawing text"] --- # List the words printed on a sheet `GET /v1/blueprints/{blueprint_id}/words` ## 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}/words` - Auth: HTTP bearer Every word printed on the sheet: its text, its position as fractions (0..1) of the page from the top-left corner, where it was read (the PDF's own text or text recognition) and the room it is printed in. Use it to search a drawing's text, or to read what is written inside one room or one region. Words come in a fixed stored order, `limit` per page; `total` counts every word that matches the filters, and `next_cursor` continues the same read until it is `null`. `rooms` maps each `room_id` on the page to the room's name. The sheet's state is never an error: `status` is `ok`, `empty` (read, and nothing is printed), `not_read` (never read: its words are unknown, not absent) or `unavailable` (try again later), with a `note`. With `room_id`, `rooms_unknown` means it is not known which words are in that room, never that the room is empty. A word whose `room_id` is `null` is outside every room only when `room_links_status` is `ok`. 404 when the sheet is not in one of your projects. 422 for an unknown field or source, a malformed `bbox`, a `room_id` that is not a room on this sheet, or a cursor from another sheet or other filters. ## Path parameters - `blueprint_id` string, required ## Query parameters - `q` string, nullable: Only words containing this text, case-insensitive. It is matched inside one word: a phrase is printed as several words, so search each word on its own. - `room_id` string, nullable: Only words printed inside this room: the room's feature `id` (as in GET /v1/blueprints/{id}) or a `room_id` a word returned. - `source` string[], nullable: Only words from these sources: digital, ocr or ocr_bubble; repeat it or pass a comma list. - `bbox` string, nullable: Only words inside this region: x0,y0,x1,y1 in fractions (0..1) of the page from the top-left corner, x1 > x0 and y1 > y0. A word is inside when the centre of its box is. - `fields` string, nullable: Per-word fields, comma-separated. The whole list, not extras: when given it replaces the default text, bbox, source, room. Also: rot, conf, polygon, id, wall, room_name. - `cursor` string, nullable: `next_cursor` of the previous page. Valid only with the same filters. - `limit` integer, nullable: Words per page; 2,000 when left out. ## Response `200` Successful Response - SheetWordsResponse - `status` 'ok' | 'empty' | 'not_read' | 'unavailable' | 'rooms_unknown', required: `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` string, nullable: A plain-English explanation whenever the answer is not a plain `ok`. - `frame` 'page_fraction': Every position is a fraction (0..1) of the page, from the top-left corner. - `page` object, nullable: The page's `width` and `height` in PDF points (1/72 inch). - `ocr` SheetWordsOcr - `tiles` integer, nullable: How many image tiles the recognition read. - `basis` string, nullable: 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` integer, nullable: Tiles that could not be read, so their words are missing; `null` when unknown. - `counts` object, nullable: Words on the whole sheet per source, before any filter. - `total` integer, nullable: Words matching the filters, across all pages; `null` when unknown. - `next_cursor` string, nullable: Pass it as `cursor` for the next page; `null` on the last page. - `words` SheetWord[]: This page of words, in a fixed stored order. - `text` string, nullable: The word as printed. - `bbox` number[], nullable: Upright box around the word, [x0, y0, x1, y1] in fractions (0..1) of the page from the top-left corner. - `source` 'digital' | 'ocr' | 'ocr_bubble', nullable: 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` string, nullable: 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` string, nullable: The room's name, repeated on the word (only with `fields=...,room_name`). - `rot` integer, nullable: Reading direction in quarter turns: 0 left to right, 1 top to bottom, 2 upside down, 3 bottom to top. - `conf` number, nullable: Recognition confidence, 0..1; always 1.0 for `digital` words. - `polygon` array[], nullable: The word's exact outline as [[x, y], ...] page fractions, following rotated text. - number[] - `id` string, nullable: The word's id in the sheet's indexed text layer; `null` when the word is not in it. - `wall_id` string, nullable: The wall the word is printed on, if any. - `rooms` object, nullable: Each `room_id` on this page mapped to the room's name. - `room_links_status` 'ok' | 'not_indexed' | 'unavailable', nullable: 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. ## Other responses - `404`: The sheet is not in one of your projects. - `422`: The request is refused. An unknown field or source, a malformed `bbox`, a `room_id` that is not a room on this sheet, or a cursor from another sheet or other filters. These answer `{"detail": {"error", "details"}}`. A parameter or body field of the wrong type or out of its range is refused before the request is read, with `{"detail": [{"loc", "msg", "type"}, ...]}`. --- [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)