---
title: "One item with its body, values and list"
method: GET
path: "/api/v1/items/{id}"
tags: ["Items"]
---

# One item with its body, values and list

`GET /api/v1/items/{id}`

## Request

- Base URL: `https://api.roma.app`
- URL: `https://api.roma.app/api/v1/items/{id}`
- Auth: HTTP bearer

Read one item in full by its id — the thing to read before working on it, the call when the person asks to see, open or show one item (search and list_items find it; this shows it), and the companion to search, which returns only the matched passage. Returns the item with `body` (the body as Markdown with a short handle in front of every block; update_items edits target those handles), `bodyVersion` (what a whole-body rewrite is pinned to), its status and due date where its list keeps them, `values` by property id with `cells` by property name beside them, its list (`list.instructions` where the list has standing instructions; they apply to the item), `guidance` (a line about working this item: its status, what the person wrote in its chat since an agent last posted, where the work goes) and, for an item a meeting was recorded into, the attributed transcript once its recording is done, with `summary` and `taskCandidates`.

## Path parameters

- `id` string, required

## Query parameters

- `includeImageUrls` boolean: true additionally returns a short-lived signed `url` per attachment so the images can be viewed. Off by default.
- `includeImages` boolean: true additionally returns the body's pictures themselves as image content blocks (up to ten, in body order, each under a line naming it) so they can be looked at — the way to read a screenshot or a receipt pasted into the body. Off by default.

## Response `200`

The tool's result.

- object
  - `id` string, required
  - `identifier` string, nullable: The item's fixed ID — its list's prefix and a number, TASK-1601 — which every item tool takes as its id too.
  - `title` string, nullable
  - `body` string, nullable: The body as Markdown; with a short handle in front of every block on a read made for editing.
  - `bodyVersion` string: A fingerprint of the body as read; a whole-body `rewrite` names it as `baseVersion`.
  - `taskStatus` string, nullable: On a list that keeps a status.
  - `dueAt` string, nullable: On a list that keeps a due date: the instant stored; a day when hasDueTime is false.
  - `hasDueTime` boolean, nullable: Whether dueAt's time of day is meant; false for a day.
  - `reminderAt` string, nullable: When the reminder rings, as an instant; null for none.
  - `completedAt` string, nullable
  - `values` object: The item's values keyed by property id; a select value is an option id.
  - `cells` object: The item's values by property NAME, as text, where its list has properties of its own.
  - `isSharedWithMe` boolean: Shared with the person by its owner; `editable` says what update_items admits on it.
  - `editable` 'all' | 'titleAndBody': On a row shared with the person: `titleAndBody` for an item shared with them one by one (its status, due date, values and images are its owner's; update_items refuses them by name), `all` for an item on a list shared with them (every field but the owner's favorite).
  - `listId` string, nullable
  - `listName` string, nullable
  - `listIcon` string, nullable: The list's own icon, an emoji, when it has one.
  - `expertId` string, nullable: The id of the item's standing expert (one of the user's experts, list_experts), when the user's own item carries one: that expert answers by default in the item's chat in Roma. Absent on a row shared with the user.
  - `createdAt` string, nullable
  - `updatedAt` string, nullable
  - `editedAt` string, nullable
  - `archivedAt` string, nullable
  - `recordingStatus` string
  - `attachments` object[]
    - `bucketPath` string, required
    - `mimeType` string, required
    - `sizeBytes` number, required
    - `url` string
  - `bodyImages` object[]: The pictures the body shows (`![…](roma://attachment/<bucketPath>)`), whether or not they are attachments, with the size each was stored at (null when unknown) and its alt text; with includeImageUrls, a short-lived signed url on each; with includeImages on get_item, the pictures themselves as image content blocks.
    - `bucketPath` string, required
    - `width` number, nullable, required
    - `height` number, nullable, required
    - `alt` string, required
    - `url` string
  - `guidance` string, required: How to work this item right now: its status, what the person wrote in its chat since an agent last posted, where the work goes.
  - `expert` object, nullable: The item's standing expert, when the user's own item carries one: that expert answers by default in the item's chat in Roma, and get_expert reads its instructions. Null on a row shared with the user.
    - `id` string, required
    - `name` string, required
  - `list` object: Present when the item's list carries standing instructions: they apply to every item on it, this one included.
    - `instructions` string, required: The list's standing instructions, as the person wrote them.
  - `label` string: For an item with no title: its first non-empty value, else its list's name.
  - `properties` object[]: The list's own properties, so a value can be written back by id.
    - `id` string, required
    - `name` string, required
    - `type` string, required
    - `kind` string: What the property IS: "status" / "dueDate" for the reserved pair a list binds to the task columns, else its type. A select named Status on any other list is a plain select.
    - `options` object[]
      - `id` string, required
      - `label` string, required
    - `optionCount` number
  - `webUrl` string, required: The item's page in Roma, to open in a browser.
  - `appUrl` string, required: The item in the Roma Mac app: the app's own link scheme (yamo://artifacts/:id; yamo-staging:// against staging).
  - `transcript` string
  - `recording` object
    - `durationMs` number, nullable, required
    - `speakers` object[], required
      - `key` string, required
      - `label` string, required
  - `summary` object
  - `taskCandidates` object[]
    - `text` string, required

## Other responses

- `400`: The request was understood and refused; the error says what to change.
- `401`: No usable bearer token.
- `404`: No such item for this account.
- `405`: The path exists but not with this method; Allow lists the ones that work.
- `429`: Over the rate limit; wait for Retry-After.

---

[API](https://skmtc.dev/roma/apis/roma-api.md) - [All operations](https://skmtc.dev/roma/apis/roma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roma/apis/roma-api/revisions/3dd91459b0fb?raw)