Items

Create items on a list, many in one call

Create items on one list, many in one call (1 to 100): a to-do or a dictated list of them on the Tasks list, a note on the Notes list, rows of a reading list or a CRM. Each entry carries a title, a body as Markdown, and values for the list's own properties as {propertyId, value} pairs (ids or names from list_lists; a select value may be its label or option id, a multiSelect value an array of them; an unknown label becomes a new option). On a list that keeps a status and a due date an entry may set taskStatus, dueAt (a day, or a local time when one was stated, which also arms a reminder at that moment) and reminderAt (a reminder on a day, at the person's default reminder hour). The items are stored as written and indexed for search; no AI pass runs unless enrich is true, which on a tasks list derives the title and due date from the words. An entry's externalId (the caller's own id) makes re-sending safe: the same externalId returns the item already made, under existing. With matchOn, an entry whose named values match an existing item fills that item's empty values, body and images and overwrites nothing (changing a filled value is update_items' job); without it every entry is inserted. Images come as imageUrls (a Roma storage path from create_image_upload, or a public https image URL the server downloads); failures come back in imageFailures. One bad entry never fails the batch; it is reported under failed with its reason.

post/api/v1/items

Request

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

Request body

listIdstring

The list every item lands on: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list, made afresh when the user deleted theirs). Omit for the Tasks list.

matchOnstring[] nullable

Property ids or names that identify an existing item. When given, an entry whose listed values all match an existing item is not added again: the existing item gains the entry's values for its empty cells, its body if it had none, and its images, and keeps every cell it already had; matching is exact. Omit to always insert — no property is a natural key, so there is no default dedup.

enrichboolean nullable

Run Roma's background AI pass on each item of a tasks list (title cleanup, due date and list suggestions). Default false: the items are stored as written.

Response

Created; the body is the new item.

listIdstring required
listNamestring required
listIconstring nullable

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

addednumber required

Items inserted by this call.

mergedIdsstring[] required

Existing items an entry was merged into through matchOn.

unknownKeysstring[] required
imagesAttachednumber required

Changes

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