create_expert
ChatGPTCreate an expert for the user: a name and its whole standing instructions as Markdown (second person, present tense, what to do; the shape the user's other experts have). Use it on the user's explicit ask to create one, never because they described how they want one answer written. A name the user already has is refused. The new expert shows in Settings → Experts in Roma, where it answers in the user's chats when mentioned by name.
create_image_upload
ChatGPTGet pre-signed URLs to upload images DIRECTLY into Roma storage — the reliable alternative to passing third-party links in imageUrls (those must stay fetchable until the server downloads them; short-lived signed links often expire first). For each slot: HTTP PUT the raw image bytes to uploadUrl with the matching Content-Type header (valid ~2 hours), then pass its bucketPath as an imageUrls entry in create_items / update_items. Keep images at or under 10 MB (maxBytes). Up to 10 slots per call.
create_items
ChatGPTCreate 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 and dueAt. 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.
create_list
ChatGPTCreate 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. Otherwise properties shape it (a reading list with Author and Status, a CRM with Company and Email); omit both to start with one default text property. Check list_lists or get_context first so an existing list is not duplicated. Returns the list with its id and its properties' stable ids, ready for create_items.
delete_items
ChatGPTDelete items by id, up to 50 per call. SOFT delete: every item stays recoverable for ~30 days via restore_deleted (type "item") before it is purged, and drops out of search. Returns the deleted items; ids that are not the user's own items are reported under refused and the rest still delete.
delete_list
ChatGPTDelete a list by id. Deleting the list also deletes EVERY item on it. SOFT delete: the list and its items are recoverable for ~30 days via restore_deleted (type "list"), which brings the items deleted with it back too. When the list still holds items the call refuses unless confirmDeleteItems is true, so the blast radius is always named before it happens. The hub's own Tasks list and Life Admin cannot be deleted.
get_automation
ChatGPTRead one of the signed-in user's own automations: its name, what it does, when it runs, its status, the next run, its steps as the user wrote them, and how the last run ended. A read only: it starts nothing and changes nothing; run_automation starts one, list_automations lists them all, get_automation_runs reads the runs.
get_automation_runs
ChatGPTRead one automation's recent runs, newest first: when each ran, how it ended, what it wrote (one line per action), the message it left for the user, and any error. Use it for "what did my morning brief find", "why did it fail", or to read the result of a run started with run_automation once it has finished.
get_blame
ChatGPTWho wrote each line of an item's body as it stands now: the body as numbered lines and runs of lines, each run with its writer (a person, their agent over this connection, the operator, an expert, an automation), the time, and the versionId of the snapshot that write replaced — the body line read_log names and get_version reads as a diff. A line belongs to the newest write that introduced or last changed its text; a line that only moved keeps its writer; a blank line joins the run above it. Lines older than the first snapshot are the item's creator's. The walk reads up to 500 snapshots back and says when it was cut (truncated, those runs with no writer). fromLine and toLine (1-based, inclusive) answer a window of the body.
get_context
ChatGPTUse this at the start of a conversation that involves the user's Roma workspace, or when you need an overview of it. Returns, in one call: how Roma works; the user (name, timezone, today's date and local time); what they asked the AI to remember about them; their lists with ids, properties and item counts (the Tasks list and the Notes list named by id); overdue, due-today, in-progress and upcoming tasks; the newest unsorted tasks; recently touched notes; their automations with the last run; and the last few days of activity. Everything comes with ids for follow-up calls. It is an overview, not the full data: use search, list_items, query_items or get_item for depth. Pass focusListId to scope the task sections to one list.
get_expert
ChatGPTRead one of the user's experts in full: its name and its standing instructions as Markdown, the way the user wrote them in Roma. Use it when the user names an expert for the work at hand ("use my Content Editor on this"), asks what one of them covers, or before updating one. By id (from list_experts or get_context) or by its exact name; a name that is none of theirs is not found.
get_guide
ChatGPTThe Roma guide for agents as text: the common part and your kind's section, the same as roma.app/agents.md and /agents/<kind>.md, for the texts you copy for the person, whole. Call it once after connecting; pass kind when Roma does not know yours yet. Both parts together are long (about 50 KB): pass part "section" when you read the common part already, "common" for the common part alone.
get_item
ChatGPTRead 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, 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_job
ChatGPTRead the progress of a queued bulk write: a create_items, update_items, delete_items or delete_list call of more than 20 entries (or 2 MB) is accepted and answers a job instead of writing at once; the entries land in the background a few at a time. Returns the job's state (queued, running, done, failed), how many entries landed and how many failed, and each entry's outcome with the item it made or changed, or the reason it failed. Poll every few seconds until status is done or failed; the items appear on the list as they land.
get_version
ChatGPTRead one version of an item's or expert's body from list_versions or from a body line of read_log (its versionId): the body as it was at that snapshot, as Markdown, with its cells, and the line changes from it to the next state — diffAgainst "current" (the default) for the body as it is now, or another version id (the next body line's versionId in the log) for the edit that one line made. The diff is hunks of removed, added and context lines, so a long body that changed in three places answers those three places; a line that is a picture or a file carries media beside its Markdown, and a hunk whose words did not change is kind: "formatting"; includeBody: false answers the diff alone.
grep_items
ChatGPTFind the lines of one list's item bodies that match a pattern — a literal by default, a regular expression with regex: true — the way grep does, when the words are known: a function or flag name, a heading, an exact phrase. search finds by meaning and answers a passage; this answers every matching line with the block handle it sits in, the handle update_items' edits take, and a line of context each side, newest item first. The person's own list, or one shared with them. Case-folded unless caseSensitive; a regular expression is the database's grammar (POSIX), tested line by line.
list_agents
ChatGPTThe user's agents — the records under Settings → Agents — and whether Roma can reach each one right now (connected: its door proven and not stale, the record bound, its client not signed out). Only a connected remote agent (isRemote and connected) can be a delegate; the names here are the names delegate takes on create_items and update_items and delegateNewItemsTo takes on update_list. Returns each record's id, name, kind, whether it is remote, whether it is connected, its state, when Roma last heard from it and when it was last reachable.
list_automations
ChatGPTList the user's automations — standing orders Roma runs on its own, on a schedule or on demand. Returns each one's id, name, what it does, status (active / paused / draft), when it runs, the next run, and how the last run ended. Use it when the user asks what runs on its own, when something runs next, or before reading or starting a run.
list_deleted
ChatGPTThe trash: everything soft-deleted in the last ~30 days — items and lists — newest first, each with the moment it is purged forever (purgesAt). Anything listed here can be brought back with restore_deleted. Filter by type, or omit type for both.
list_experts
ChatGPTList the user's experts: each a named body of standing instructions they wrote in Roma for a kind of work (an editor, a reviewer, a coach), private to them. Returns every expert's id, name and the opening line of its instructions. Use it when the user asks which experts they have, names one, or asks for work done the way one of their experts does it; get_expert reads one in full.
list_items
ChatGPTList, filter and search items. Omit listId for the Tasks set — every item on a list that keeps a status and a due date (the Tasks list and every list made for tasks), ordered by due date then creation, completed tasks left out by default. Pass listId for one list's items, whatever its shape: a notes list's prose, a reading list's rows. Each row carries the item's title, body as Markdown, status and due date where its list keeps them, values keyed by property id, and its list. get_item reads one item in full with handles for editing, and is the call when the person asks to see, open or show one item; query_items filters, counts and sums by property. A read that repeats on a schedule passes changedSince, the nextChangedSince of its previous read: only what moved since comes back on the person's own lists, deletions included, one call per cycle instead of the whole list.
list_lists
ChatGPTThe user's lists: every live list with its id, name, icon, standing instructions, item count, layout and PROPERTIES with their stable ids — the ids create_items and update_items key values on. A list whose statusPropertyId is "status" and dueDatePropertyId is "dueDate" keeps a status and a due date on its items, which makes them tasks; the Tasks list and the Notes list are named by id. Use it to resolve a list's name to its id before writing to it, or to read a list's properties you have not seen yet. Pass suppressOptions: true when you only need names and counts; a select property can carry hundreds of options (a select value may be sent as its label).
list_versions
ChatGPTList the version history of one item or expert, newest first: one entry per write, each with who made it (user, ai or system, and the name it was signed with when there is one) and the cause (an edit in the app, an edit over this connection, a restore, Roma's own passes). Each entry is the body as it was BEFORE that write, so the entry naming an edit is the state that undoes it; restore_version puts one back. Use it to undo an edit, or to see how a body or an expert's instructions changed over time.
lookup_memories
ChatGPTRead Roma's journal of what happened: one entry per day, week or month, written by Roma from the user's tasks, notes, chats and connected apps (never the user's own words). Use it for "what did I do with the accountant in March", "what happened last week", or anything before the few days get_context carries. A span (from, to; 90 days back by default, up to yesterday) and, when given, two to five plain words an entry would contain; a long span without words answers headlines only, to narrow the next call. A day entry names the tasks and notes it touched with their links. Returns entries newest first and a note about what was searched; nothing is invented when the journal has nothing.
manage_sections
ChatGPTMake, rename, delete, hide or show a sidebar section (the groups the user's lists stand in; list_lists and get_context carry them in order). create makes an empty section at the end, or answers the section that already wears the name; rename renames one (the default section too — its name is Lists until renamed; "" puts Lists back); delete removes a section and its lists return to the default section (the default section is never deleted); hide / show fold a section out of or back onto the sidebar on every device. To put a list INTO a section use create_list or update_list with section.
manage_sharing
ChatGPTRead or change who a list or an item is shared with. members reads who is on it: the members with their level, the pending invitations and the public link. invite sends an email invitation to each address in emails at level — "edit" (Can edit, the default) or "full" (Can edit and invite); there is no viewer level. link turns the public link on or off (linkOn): on, anyone with the link can edit. remove takes a member off (member: a name or user id), leave takes the user off a list or item somebody shared with them, stop ends the sharing for everyone. An invite, and a link turned on, answer a PREVIEW first (preview: true, with wouldInvite or wouldMakeLinkOn) and change nothing until the same call is repeated with confirm: true; the other actions run at once. Who may do what: the owner turns the link, removes a member and stops the sharing; the owner or a member with full access invites; a member leaves. An item held through a shared list is left or removed through the list, not the item. Returns the action, the subject (kind, id, title, isShared) and the action's own fields: members and invitations for a read; results per email (outcome, sent) for an invite; shareUrl and linkOn for the link; removed, left or ended. A subject the user cannot reach, a member nobody answers to, or an action the user's standing does not allow is refused with the reason.
manage_triggers
ChatGPTThe signed-in user's own triggers, in one tool: action list, create, update or delete. A trigger says which Roma events (an item created, changed or delegated, a reply posted, a list changed) are delivered to the user's own agent, and how: transport webhook POSTs each delivery to the https address the user's agent names in url, signed with the trigger's secret (Standard Webhooks); transport poll has no address, the agent reads its deliveries from Roma's deliveries route with its own key. Each delivery carries the item as get_item returns it, what changed, and who changed it. A failing address is retried three times over a day, then the trigger pauses; update resumes it or gives it a new address. agentName ties the trigger to the name the agent posts under, so the user's replies to its posts are delivered too. The transport never changes on update; delete and create again. Twenty per account. Delete removes the trigger and its delivery history, and the chat confirms first. list answers the triggers, each one's last delivery, and the catalogue of events: item.created (an item was created on one of the person's lists: a task, a note, a row); item.updated (an item's title, due date, reminder, a property value or its archived flag changed); item.statusUpdated (a task's status changed (todo, inprogress, completed)); item.moved (an item moved onto another list); item.deleted (an item was deleted into the trash (recoverable for 30 days)); item.restored (an item came back from the trash); list.created (a list was created); list.updated (a list's name, icon, instructions, properties or archived flag changed); list.deleted (a list was deleted into the trash); list.restored (a list came back from the trash); item.delegated (the person delegated an item to an agent: the item's delegate cell gained the agent's record (data); message.posted (the person replied to an agent's post in an item's chat (reply on its row; data); automation.completed (an automation's run finished (`data).
move_items
ChatGPTMove items onto another list: a task out to the Tasks list ("tasks"), a note onto the Notes list ("notes"), anything onto a list by id. Each item keeps its id, body, chat and history; its values follow their properties by id, then by name and type, select values by label. A value the destination list has no place for would be DROPPED: a first call that would drop values answers a preview (preview: true, droppedValues) and moves nothing; the same call with acknowledgeDataLoss: true then moves. The status and due date ride along unseen onto a list that keeps neither and show again on the way back. Items that are not the user's own are reported under refused, never moved.
post_chat_message
ChatGPTPost a message into an item's chat as the calling agent: an action taken outside Roma with its link, or the one question the work is blocked on. The user sees it on every device as an unread reply on the item and as a line in their main conversation, and the agent cannot take it back, so a post per step, or a note that work is finished, reads as noise. Set needsInput when the work is blocked on their answer. The same messageKey posted twice lands once.
query_items
ChatGPTFilter, sort, count or sum the items of ONE list by its properties — exact numbers instead of eyeballing a dump: "how many are unread", "expenses in March", "the wines rated 5". where clauses AND-combine on a property by id or name (on a list that keeps them, status and dueDate are properties too); a select value may be its label. mode 'list' (default) returns the matching items, paged with offset and limit; 'count' how many match; 'sum' the total of sumPropertyId across the matches. Archived items are left out unless includeArchived: true; each item reports its archivedAt.
read_chat_messages
ChatGPTRead the recent messages in an item's chat: what the user said there, what Roma replied, and what any agent posted with post_chat_message. Pass since to read only what arrived after a moment you already saw; a read that repeats on a schedule passes the createdAt of the last message it saw every time. Empty when the item has no chat yet.
read_log
ChatGPTRead an item's (or a list's) log, Roma's own record of everything that happened to it: every change with who made it and when — a person, Roma's operator, an expert, an agent, an automation — every body change with what it did and the text it added (change and body) and the snapshot it replaced (versionId), every post in its thread (messageId), the summary's own writes. No agent writes into it; read it to see what changed before you and why, before continuing another agent's work. Pass since (the seq of the last line you saw) to read only what landed after it, oldest first; without it the newest lines, newest first, with nextBeforeSeq for the page before. The body itself is get_item's; the thread's words are read_chat_messages'.
register_agent
ChatGPTTell Roma which agent you are, once after connecting: register_agent with your kind from the list, or with the id from the message the person pasted. Roma then files this connection under the person's agent record of that kind in Settings → Agents, making the record when there is none, and names that record on your posts. With both, agentId wins. Calling again keeps the same record, and nothing is lost: the record, its key and its history stay; a url given again only updates where Roma delivers, and the user can change or remove any of it in Settings → Agents at any time. A kind outside the list is refused. After it the person can hand you items (the item's Delegate cell shows your record), Roma delivers each delegation and each reply to your posts through your door, and list_items with delegatedTo "me" (or the agent block of get_context) reads your work. On a webhook door Roma POSTs the delivery to the address given here, signed the Standard Webhooks way, text the one-line reason and data.item the item with its webUrl. Answers next, what to do now for your kind, and in agent the record's facts: signalUrl (the public address a hook of yours peeks at, Muse), pollUrl with triggerId (where a program reads its deliveries with its key), mailAddress (the confirmed address Roma mails, Instinct or a mail door; null until confirmed), keyRoad (how your kind uses a key: "bearer" on every call, "signin" as the key on Roma's key sign-in page, null when your kind never needs one), hasKey (a live key exists for the record; the person makes one on the record's page), keyMadeAt (when the newest live key was made) and settingsUrl (the record's page in Settings → Agents, where the person makes the key and pastes an address).
restore_deleted
ChatGPTBring back one soft-deleted item or list from the trash (see list_deleted). Restoring a list also brings back the items deleted with it; an item whose list is still in the trash can't come back alone (restore the list first). An item whose list is gone for good lands on the hub's default list for what it was (movedToDefaultList: true). Restores one thing per call. If it is already live the call succeeds with alreadyLive: true.
restore_version
ChatGPTRestore one item's or expert's body to an earlier version from list_versions (its cells too, where the snapshot kept them). The current body is snapshotted first, so a restore is itself undoable. When the person, or a collaborator, edited the body in Roma after that version, the call answers needsConfirmation and names those later edits instead of restoring; the same call with acceptLaterEdits: true, after the person agreed to lose them, restores. Writes made over this connection never ask: undoing them is what the tool is for.
run_automation
ChatGPTStart one of the user's automations now — the same as Run now on its page in Roma. Use it only when the user asks to run a specific automation. The run happens inside Roma with the user's connected apps and can take a minute; its result lands in the user's Roma chat, not in this conversation. Read the outcome afterwards with get_automation_runs. Refused for a draft, while the same automation is already running, or once the daily run limit is reached.
search
ChatGPTSearch the user's Roma workspace — their items (tasks, notes, the rows of every list they keep) and their lists — by meaning or keyword (hybrid semantic + keyword retrieval). Use this when the user asks about their own information, plans or anything they may have saved, and before adding something that may already exist. Their wording often won't match their notes' wording; the semantic arm bridges that gap (and across languages). Returns the best-matching passage per item, each with its list; get_item returns an item in full. An empty result means nothing relevant is saved. Not for general web knowledge.
update_expert
ChatGPTUpdate one of the user's experts: its name, its instructions, or both. instructions replaces the WHOLE body: read it with get_expert first and send the whole text with the change in it, a line that contradicts an existing one replacing that line rather than sitting beside it. A rename to a name the user already has is refused. The previous body stays in the expert's version history (list_versions, restore_version). Use it when the user says an expert missed something, should work differently, or should be called something else.
update_items
ChatGPTUpdate items, many in one call, each with its own title, body edits and values; the status, due date, archive and favorite flags apply to every item in the call. Only the fields passed change; null leaves a field as it is. The body is edited with edits against the handles get_item returns in body — replace, insert, delete, setChecked, move, replaceText, or rewrite pinned to bodyVersion — applied in order, all or nothing; a refused call writes nothing on that item and returns the current body with fresh handles. The older way, body with the call's merge mode (append by default, prepend, insertAfter with anchor, replace with confirmReplace: true), still works; an item uses one or the other. values MERGE into the item (only the properties sent change; "" clears one; an unknown property is an error naming the valid ones). imageUrls add images (clearImages: true drops the old ones first). taskStatus and dueAt apply only on a list that keeps them ("none" clears the due date and its reminder). Items are written in order; a refusal stops the batch and names the items already written, so re-send only the rest. Returns each item, with body, bodyVersion and applied after a body write.
update_list
ChatGPTChange a list: its name, icon, standing instructions, layout, or its properties. instructions REPLACES the existing text (read it first with list_lists and carry forward what is still true; null clears it). addProperties adds properties (every one in this call), updateProperty renames, retypes or re-options ONE property, deletePropertyIds removes properties, columnOrder reorders them. A retype migrates the items' values; one that would clear or trim values answers a PREVIEW (preview: true, what would be lost) and writes nothing until the same call is repeated with acknowledgeDataLoss: true. The reserved status and due date properties can be renamed, never retyped or removed. Only the fields passed change.
wait_for_item
ChatGPTHold until something new lands on this item, at most 25 seconds; call again to keep waiting. For the agent that handed a task to another agent and waits for the answer in the same conversation. Answers the new log lines (the read_log shape) that were not written by you, the task's agentState at that moment, and nextSince, the seq to pass as since on the next call. until says what ends the wait: "return" (a returned or released line: the other agent gave the task back, or Roma released it: silent for four hours, the chain stopped, a failed run, or the person reassigned it; any released line ends the wait), "post" (a post by someone else), or "any" (default: any new line by someone else). timedOut: true means nothing came in time; call again. One wait per item at a time: a second call while one waits answers at once with busy: true.
add_collection_items
Claudecreate_collection
Claudecreate_image_upload
Claudecreate_note
Claudecreate_project
Claudecreate_task
Claudecreate_tasks
Claudedelete_collection
Claudedelete_collection_items
Claudedelete_note
Claudedelete_task
Claudeget_automation_runs
Claudeget_collection_item
Claudeget_collection_items
Claudeget_context
Claudeget_note
Claudeget_task_context
Claudelist_automations
Claudelist_collections
Claudelist_deleted
Claudelist_notes
Claudelist_projects
Claudelist_tasks
Clauderestore_deleted
Clauderun_automation
Claudesearch
Claudeupdate_collection
Claudeupdate_collection_items
Claudeupdate_note
Claudeupdate_project
Claudeupdate_task
Claude