ROroma
Items

One item with its body, values and list

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.

get/api/v1/items/{id}

Request

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

Path parameters

idstring required

The item's id (from list_items, query_items, search or get_context), or a Roma link to the item (roma.app/artifacts/<id>, roma://task/<id>): a link the person pasted names one item, and this reads it.

Query parameters

includeImageUrlsboolean

true additionally returns a short-lived signed url per attachment so the images can be viewed. Off by default.

includeImagesboolean

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

The tool's result.

idstring required
identifierstring nullable

The item's fixed ID — its list's prefix and a number, TASK-1601 — which every item tool takes as its id too.

titlestring nullable
bodystring nullable

The body as Markdown; with a short handle in front of every block on a read made for editing.

bodyVersionstring

A fingerprint of the body as read; a whole-body rewrite names it as baseVersion.

taskStatusstring nullable

On a list that keeps a status.

dueAtstring nullable

On a list that keeps a due date: the instant stored; a day when hasDueTime is false.

hasDueTimeboolean nullable

Whether dueAt's time of day is meant; false for a day.

reminderAtstring nullable

When the reminder rings, as an instant; null for none.

completedAtstring nullable
valuesobject

The item's values keyed by property id; a select value is an option id.

cellsobject

The item's values by property NAME, as text, where its list has properties of its own.

isSharedWithMeboolean

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

listIdstring nullable
listNamestring nullable
listIconstring nullable

The list's own icon, an emoji, when it has one.

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

createdAtstring nullable
updatedAtstring nullable
editedAtstring nullable
archivedAtstring nullable
recordingStatusstring
guidancestring 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.

labelstring

For an item with no title: its first non-empty value, else its list's name.

webUrlstring required

The item's page in Roma, to open in a browser.

appUrlstring required

The item in the Roma Mac app: the app's own link scheme (yamo://artifacts/:id; yamo-staging:// against staging).

transcriptstring
summaryobject

Changes

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