ROroma
Lists

Create a list

Create a list. template "tasks" creates a list for to-dos: its items keep a status (todo / inProgress / completed) and a due date, like the Tasks list; properties given with it are added beside those two (an Agent person property, say). Otherwise properties shape it (a reading list with Author and Status, a CRM with Company and Email); omit both to start with no properties — every item has a title. Check list_lists or get_context first so an existing list is not duplicated. section places the list in a sidebar section (an existing section's id or name, or a new name, which makes the section); omitted, the list lands in the default section. Returns the list with its id and its properties' stable ids, ready for create_items.

post/api/v1/lists

Request

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

Request body

namestring required

The list's name, in the user's own words.

sectionstring nullable

The sidebar section to place the list in: a section's id or name from list_lists, or a NEW name, which makes the section. Omit, or pass null, for the default section.

iconstring nullable

An emoji for the list.

instructionsstring nullable

Standing rules for how entries should be handled, one rule per line. Max 500 characters — they ride in the prompt on every turn.

template'tasks' nullable

"tasks" creates a list for to-dos that keeps a status and a due date. Omit for a list shaped by properties.

titleLabelstring nullable

What the title column is headed on this list — the word every item's name sits under: Name on a CRM, Book on a reading list. Omit for Title. Never a property: every item has a title.

Response

Created; the body is the new item.

idstring required
namestring required
iconstring nullable
instructionsstring nullable
titleLabelstring nullable

The title column's name on this list (Name on a CRM, Book on a reading list); null reads as Title. An item's name is its title under any label.

layoutstring
role'tasks' | 'notes' | 'other'

What the list's items are, read from its properties: "tasks" when it keeps the status and the due date, "notes" when it has no properties, "other" when its properties are its own.

statusPropertyIdstring nullable

"status" when the list keeps its items' status in the task columns.

dueDatePropertyIdstring nullable

"dueDate" when the list keeps its items' due date in the task columns.

itemCountnumber

The list's open items: every live item but a repeating template, and never a completed one on a list that keeps its status in the task columns.

isLifeAdminboolean
isPinnedboolean

true when the user pinned the list to the top of the sidebar, beside Tasks.

warningstring

Changes

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