REST API
Plain HTTP for the tools that speak it rather than MCP: Zapier, Make, n8n, a shell script, a scheduled job. 50 operations under https://api.roma.app/api/v1, each one of the MCP server's tools wearing an HTTP method, so what you can do here is exactly what an MCP client can do and the parameters are the same. The document that describes it is at /api/v1/openapi.json; import it into Zapier, Postman or an OpenAPI client.
How to call
- Base URL
https://api.roma.app/api/v1. JSON in, JSON out. - Authentication: a Roma API key or an OAuth access token as a bearer:
Authorization: Bearer roma_…. Create a key in Roma under Settings, then Connections. Authentication has the details. - Ids are UUIDs; get them from
GET /context, the list routes orGET /search. An id that belongs to someone else answers404. - Query parameters are typed by the schema:
limit=5,includeArchived=true, a list astaskStatus=todo,inProgress. - Errors are
{ "error": "one sentence", "code": "invalid | notFound | methodNotAllowed | unauthorized | rateLimited | toolError" }with400,401,404,405or429. A429carriesRetry-After; a405carriesAllow. - Rate limit: 60 requests a minute per key or token, counted before authentication, so a bad key is counted too.
- Status codes: a route that makes something answers
201(POST /lists,POST /sections,POST /items,POST /items/{id}/messages,POST /uploads,POST /triggers,POST /experts); everything else200. Deletes are soft:GET /trashandPOST /trash/restorebring things back for about 30 days.
Adding a task
The one call most automations need: a line of text becomes a task on the Tasks list. POST /items takes one or many; listId is a list's id, or the word tasks for the Tasks list and notes for the Notes list. What you set yourself (dueAt, taskStatus) stays as sent; enrich: true lets the pass that runs a beat later tidy the wording and pick up the due date the text names.
curl -X POST "https://api.roma.app/api/v1/items" \
-H "Authorization: Bearer roma_…" -H "Content-Type: application/json" \
-d '{"listId": "tasks", "items": [{"title": "Call the dentist tomorrow at 10", "enrich": true}]}'
At a glance
- Context:
GET /context - Agents:
GET /agents,GET /guide - Lists:
GET /lists,POST /lists,PATCH /lists/{id},DELETE /lists/{id},POST /sections,PATCH /sections/{id},DELETE /sections/{id} - Sharing:
GET /lists/{id}/members,POST /lists/{id}/sharing,GET /items/{id}/members,POST /items/{id}/sharing - Items:
GET /items,POST /items,PATCH /items,DELETE /items,POST /items/query,POST /items/move,GET /items/{id},GET /items/{id}/versions,GET /items/{id}/versions/{versionId},GET /items/{id}/blame,POST /items/{id}/versions/{versionId}/restore,POST /uploads,GET /jobs/{id} - Chats:
GET /items/{id}/messages,POST /items/{id}/messages,GET /items/{id}/log,GET /items/{id}/wait - Search:
GET /search,GET /lists/{id}/grep - Trash:
GET /trash,POST /trash/restore - Automations:
GET /automations,GET /automations/{id},GET /automations/{id}/runs,POST /automations/{id}/run - Triggers:
GET /triggers,POST /triggers,PATCH /triggers/{id},DELETE /triggers/{id} - Experts:
GET /experts,POST /experts,GET /experts/{id},PATCH /experts/{id},GET /experts/{id}/versions,POST /experts/{id}/versions/{versionId}/restore - Memory:
GET /memory/lookup
Context
GET /context
The workspace in one call · Read-only · MCP tool get_context
Use 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; and where the workspace stands as a whole (how many items, and a line on where first items come from when it has none). 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. When this call is made under one of the user's agent records (a connected app, or a record register_agent bound), agent carries that record (id, name, kind, door) and the items delegated to it (delegated; assigned is the same list under its old name), newest change first, so an agent finds its work in the one call it already makes. Pass focusListId to scope the task sections to one list.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
focusListId | string | no | Optional list id. Scopes the task sections to that list; the rest stays workspace-wide. |
agentName | string | null | no | Who is calling, when this sign-in carries several agents (several Grok Bots of one account; ChatGPT and a Dot): your own agent's name, or its agentId. Pass it on every call. A sign-in or key with one agent is that agent whatever this says. |
Returns 200
about(string[])user(object)unavailable(string[])whoAmI(object): In place ofagent, when this sign-in carries several agents of one kind and the call named none of them:noteasks who is calling,agentslists them, each with its own delegated items. Call again with agentName.agent(object): The agent record this call is made under, with the items delegated to it, when there is one.dooris the wire word for how Roma reaches it (bridge: the agent runs on the user's own computer and is started there); the plain words the record's page uses arereachon register_agent's answer and on list_agents.links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.
Example
curl -X GET "https://api.roma.app/api/v1/context" \
-H "Authorization: Bearer roma_…"
Agents
GET /agents
The user's agents, and whether Roma can reach each one right now · Read-only · MCP tool list_agents
The 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 an agent Roma can hand work to (isRemote: a cloud agent, or a local one that is started on the user's computer) that is 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 Roma can hand it work at all (isRemote), whether it is connected, its state, when Roma last heard from it, when it was last reachable, and reach: how Roma gets a task to it, in the words of its page (started on the user's computer, its own schedule, an address, email, a subscription, or not set up yet).
Returns 200
agents(object[])
Example
curl -X GET "https://api.roma.app/api/v1/agents" \
-H "Authorization: Bearer roma_…"
GET /guide
The guide for agents as text: the index, the rules and one kind's section or help page · Read-only · MCP tool get_guide
The Roma guide for agents and the Roma skill as text, the same as roma.app/agents.md, its pages and roma.app/skill.md, for the texts you copy for the person, whole. Read index, then rules once per session, then your section; help only when a step fails. Call it once after connecting; pass kind when Roma does not know yours yet. Pass part "index" for agents.md, "rules" for agents/rules.md, "section" for your kind's page, "help" for your kind's help page; both (the default) is index, rules and section together. Pass part "skill" for the Roma skill, the same text as roma.app/skill.md, when your fetch tool refuses that address, and "skill-full" for the full skill at roma.app/skill-full.md.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
kind | string | no | Your kind, when Roma does not know it yet: chatgpt (ChatGPT), dot (ChatGPT Dot), claude (Claude), claudeCode (Claude Code), codex (Codex), muse (Muse), museCode (Muse Code), instinct (Instinct), grok (Grok), grokBot (Grok Bot), hermes (Hermes), poke (Poke), town (Town), webhook (A webhook), email (An agent with an inbox), other (Custom Agent). Left out, the record this call is made under names it. |
part | "both" | "index" | "rules" | "section" | "help" | "skill" | "skill-full" | no | Which part to return: both (the default: index, rules and your section), index (agents.md alone), rules (the rules for every kind alone), section (your kind's section alone), help (your kind's help page, for a step that fails), skill (the Roma skill, the text of roma.app/skill.md), or skill-full (the full skill, roma.app/skill-full.md). |
Returns 200
version(string): The guide's version line.index(string): agents.md as Markdown: the first message, the order of the first calls, the two parts, the links. With part both or index.rules(string): The rules for every kind as Markdown, agents/rules.md. With part both or rules.section(object | null): Your kind's section as Markdown, under its title. Null when the kind is not known or has no section of its own. With part both or section.help(object | null): Your kind's help page as Markdown. Null when the kind has no help page yet. Only with part help.skill(string): The Roma skill as Markdown, the text of this build's /skill.md (part skill) or /skill-full.md (part skill-full).pages(object)note(string): Why the section or the help page is missing, when it is.
Example
curl -X GET "https://api.roma.app/api/v1/guide" \
-H "Authorization: Bearer roma_…"
Lists
GET /lists
The lists with their properties and counts · Read-only · MCP tool list_lists
The 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). sections are the sidebar's sections in order (the default section, id "lists", and the ones the user made) and each list names its section; create_list and update_list take section to place a list.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
suppressOptions | boolean | no | true replaces each select property's option list with an optionCount — much smaller payload. |
Returns 200
total(number)tasksListId(string | null)notesListId(string | null)sections(object[]): The sidebar's sections in the rail's order, each with its lists.lists(object[])
Example
curl -X GET "https://api.roma.app/api/v1/lists" \
-H "Authorization: Bearer roma_…"
POST /lists
Create a list · Adds data · MCP tool create_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.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | The list's name, in the user's own words. |
section | string | null | no | 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. |
icon | string | null | no | An emoji for the list. |
instructions | string | null | no | 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" | null | no | "tasks" creates a list for to-dos that keeps a status and a due date. Omit for a list shaped by properties. |
properties | object[] | null | no | The list's own properties (3 to 6 is typical; a title exists on every item, so no title property). With template "tasks" they stand beside the status and the due date. |
titleLabel | string | null | no | 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. |
Returns 201
id(string)name(string)icon(string | null)instructions(string | null)titleLabel(string | null): 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.layout(string)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.properties(object[])statusPropertyId(string | null): "status" when the list keeps its items' status in the task columns.dueDatePropertyId(string | null): "dueDate" when the list keeps its items' due date in the task columns.itemCount(number): 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.isLifeAdmin(boolean)section(object | null): The sidebar section the list stands in (id and name); the default section's id is "lists".isPinned(boolean): true when the user pinned the list to the top of the sidebar, beside Tasks.warning(string)
Example
curl -X POST "https://api.roma.app/api/v1/lists" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"name":"<name>"}'
PATCH /lists/{id}
Change a list's name, icon, instructions, layout or properties · Updates or removes existing data · MCP tool update_list
Change 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. The title column is renamed through titleLabel (it stays every item's title), never retyped, removed or hidden. section moves the list into a sidebar section (an id or name from list_lists, or a new name, which makes the section; null puts it back in the default section) — on a list somebody shared with the user it files the list on their own rail. Every other field changes a list shared with the user as it changes their own: a member edits the whole list for everyone in it. isPinned pins the list to the top of the sidebar or unpins it, archived sets it aside or brings it back, and following follows or mutes its edits and its chat; the pin and the following are the user's own and work on a list shared with them to view only. Only the fields passed change.
Path
id: The list's id (from list_lists or get_context).
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
isPinned | boolean | null | no | true pins the list to the top of the sidebar (beside Tasks), false unpins it. The user's own, on a joined list too. Omit, or pass null, to leave it. |
archived | boolean | null | no | true sets the list aside (out of the sidebar, kept and reversible), false brings it back. Omit, or pass null, to leave it. |
following | object | null | no | The user's own following of the list's edits and chat: each half "follow" or "mute". The user's own, on a joined list too. Omit to leave it. |
section | string | null | no | Move the list into a sidebar section: a section's id or name from list_lists, or a NEW name, which makes the section; null moves it to the default section. Omit to leave it where it is. |
name | string | null | no | New name. Omit, or pass null, to leave it unchanged. |
icon | string | null | no | New emoji; "" removes it. Omit, or pass null, to leave it unchanged. |
instructions | string | null | no | REPLACES the standing rules (max 500 characters); "" clears them. Omit, or pass null, to leave them unchanged. |
titleLabel | string | null | no | The title column's new name on this list (Name, Book, Client); "" resets it to Title. Omit, or pass null, to leave it unchanged. The column stays every item's title under any name. |
layout | "list" | "kanban" | "table" | null | no | How the list opens: 'list', 'kanban' (the board) or 'table'. |
columnOrder | string[] | null | no | Left-to-right property order: EVERY property exactly once, by property id. |
addProperties | object[] | null | no | Properties to ADD, every one in this call. Existing items leave a new property unset. |
updateProperty | object | null | no | ONE property to rename, retype or re-option. |
statusMoveTo | string | null | no | When the reserved status's options drop ONE status that items still hold: the status id those items move to first. Without it the call is refused naming the count. |
deletePropertyIds | string[] | null | no | Stable ids of the properties to remove, every one in this call. |
acknowledgeDataLoss | boolean | null | no | true ONLY on a repeat call, after a preview reported items that would clear or trim and you told the user what will be lost. |
delegateNewItemsTo | string | null | no | Which DELEGATE each item ADDED to this list is handed to from now on: a name or id from the list's delegates in list_lists (the Operator, or one of the user's own agents, which is woken for each new item), "operator" (Roma's own first turn on each new item, the default), "nobody" (no delegate: new items stay quiet), or "default" (the account's default delegate copied onto this list — the rule every new list starts with; the list keeps it from then on). Never a person: a person is assigned, not delegated. A shared list has no default delegate; the rule is refused there. Changes nothing about the items already there, nor about how a typed title is prepared. Omit, or pass null, to leave the rule unchanged. |
Returns 200
id(string)name(string)icon(string | null)instructions(string | null)titleLabel(string | null): 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.layout(string)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.properties(object[])statusPropertyId(string | null): "status" when the list keeps its items' status in the task columns.dueDatePropertyId(string | null): "dueDate" when the list keeps its items' due date in the task columns.itemCount(number): 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.isLifeAdmin(boolean)section(object | null): The sidebar section the list stands in (id and name); the default section's id is "lists".isPinned(boolean): true when the user pinned the list to the top of the sidebar, beside Tasks.preview(boolean)warning(string)archived(boolean): Whether the list is set aside, after the call.isFollowingEdits(boolean): Whether the user follows the list's edits, after afollowingchange.isFollowingChat(boolean): Whether the user follows the list's chat, after afollowingchange.
Example
curl -X PATCH "https://api.roma.app/api/v1/lists/<id>" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{}'
DELETE /lists/{id}
Delete a list into the trash · Updates or removes existing data · MCP tool delete_list
Delete 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.
Path
id: The list's id (from list_lists).
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmDeleteItems | boolean | null | no | Required (true) when the list holds items: confirms deleting the list AND every item on it. Confirm with the user first. |
Returns 200
deleted(boolean)id(string)name(string)itemsDeleted(number)job(object): Present when the batch was past the inline threshold (more than 20 entries or 2 MB in one call): the call was accepted and stored as a job, nothing is written yet, and the entries land in the background a few at a time. Poll get_job withjob.idfor progress; the other fields of the result are empty.
Example
curl -X DELETE "https://api.roma.app/api/v1/lists/<id>" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{}'
POST /sections
Make a sidebar section · Updates or removes existing data · MCP tool manage_sections
Make, 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.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
section | string | null | no | The section's id or name (from list_lists); "lists" or its name for the default section. Not for create. |
name | string | null | no | create: the new section's name. rename: the new name ("" on the default section puts Lists back). |
Returns 201
action(string)section(object)created(boolean): create: true when the call made the section.releasedListIds(string[]): delete: the lists that returned to the default section.
Example
curl -X POST "https://api.roma.app/api/v1/sections" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{}'
PATCH /sections/{id}
Rename, hide or show a sidebar section · Updates or removes existing data · MCP tool manage_sections
Make, 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.
Path
id: The section's id or name (from list_lists); "lists" or its name for the default section. Not for create.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
action | "create" | "rename" | "delete" | "hide" | "show" | yes | What to do. |
name | string | null | no | create: the new section's name. rename: the new name ("" on the default section puts Lists back). |
Returns 200
action(string)section(object)created(boolean): create: true when the call made the section.releasedListIds(string[]): delete: the lists that returned to the default section.
Example
curl -X PATCH "https://api.roma.app/api/v1/sections/<id>" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"action":"create"}'
DELETE /sections/{id}
Delete a sidebar section; its lists return to the default section · Updates or removes existing data · MCP tool manage_sections
Make, 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.
Path
id: The section's id or name (from list_lists); "lists" or its name for the default section. Not for create.
Returns 200
action(string)section(object)created(boolean): create: true when the call made the section.releasedListIds(string[]): delete: the lists that returned to the default section.
Example
curl -X DELETE "https://api.roma.app/api/v1/sections/<id>" \
-H "Authorization: Bearer roma_…"
Sharing
GET /lists/{id}/members
Who a list is shared with: members, pending invitations, the public link · Updates or removes existing data · MCP tool manage_sharing
Read 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.
Path
id: The list's id (from list_lists). One of listId / itemId.
Returns 200
action(string)subject(object)preview(boolean): true: nothing changed; repeat the call with confirm: true to do it.wouldInvite(string[]): preview of an invite: the addresses that would be emailed.level(string): preview of an invite: the level they would get.wouldMakeLinkOn(boolean): preview of a link turned on.note(string)members(object[])invitations(object[])results(object[])shareUrl(string | null)linkOn(boolean)removed(boolean)left(boolean)ended(boolean)
Example
curl -X GET "https://api.roma.app/api/v1/lists/<id>/members" \
-H "Authorization: Bearer roma_…"
POST /lists/{id}/sharing
Invite people to a list, turn its public link on or off, remove a member, leave it, or stop sharing it · Updates or removes existing data · MCP tool manage_sharing
Read 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.
Path
id: The list's id (from list_lists). One of listId / itemId.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
action | "members" | "invite" | "link" | "remove" | "leave" | "stop" | yes | What to do. |
itemId | string | null | no | The item's id, its ID (ROMA-12) or a Roma link to it. One of listId / itemId. |
emails | string[] | null | no | invite: the email addresses to invite. |
level | "full" | "edit" | null | no | invite: the level every invitee gets — "edit" (Can edit, the default) or "full" (Can edit and invite). |
linkOn | boolean | null | no | link: true turns the public link on (anyone with it can edit), false turns it off. |
member | string | null | no | remove: the member to take off, by name or user id. |
confirm | boolean | null | no | true on the repeat of an invite, or of a link turned on, after the preview: the call then sends the emails or turns the link on. |
Returns 200
action(string)subject(object)preview(boolean): true: nothing changed; repeat the call with confirm: true to do it.wouldInvite(string[]): preview of an invite: the addresses that would be emailed.level(string): preview of an invite: the level they would get.wouldMakeLinkOn(boolean): preview of a link turned on.note(string)members(object[])invitations(object[])results(object[])shareUrl(string | null)linkOn(boolean)removed(boolean)left(boolean)ended(boolean)
Example
curl -X POST "https://api.roma.app/api/v1/lists/<id>/sharing" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"action":"members"}'
GET /items/{id}/members
Who an item is shared with: members, pending invitations, the public link · Updates or removes existing data · MCP tool manage_sharing
Read 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.
Path
id: The item's id, its ID (ROMA-12) or a Roma link to it. One of listId / itemId.
Returns 200
action(string)subject(object)preview(boolean): true: nothing changed; repeat the call with confirm: true to do it.wouldInvite(string[]): preview of an invite: the addresses that would be emailed.level(string): preview of an invite: the level they would get.wouldMakeLinkOn(boolean): preview of a link turned on.note(string)members(object[])invitations(object[])results(object[])shareUrl(string | null)linkOn(boolean)removed(boolean)left(boolean)ended(boolean)
Example
curl -X GET "https://api.roma.app/api/v1/items/<id>/members" \
-H "Authorization: Bearer roma_…"
POST /items/{id}/sharing
Invite people to an item, turn its public link on or off, remove a member, leave it, or stop sharing it · Updates or removes existing data · MCP tool manage_sharing
Read 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.
Path
id: The item's id, its ID (ROMA-12) or a Roma link to it. One of listId / itemId.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
action | "members" | "invite" | "link" | "remove" | "leave" | "stop" | yes | What to do. |
listId | string | null | no | The list's id (from list_lists). One of listId / itemId. |
emails | string[] | null | no | invite: the email addresses to invite. |
level | "full" | "edit" | null | no | invite: the level every invitee gets — "edit" (Can edit, the default) or "full" (Can edit and invite). |
linkOn | boolean | null | no | link: true turns the public link on (anyone with it can edit), false turns it off. |
member | string | null | no | remove: the member to take off, by name or user id. |
confirm | boolean | null | no | true on the repeat of an invite, or of a link turned on, after the preview: the call then sends the emails or turns the link on. |
Returns 200
action(string)subject(object)preview(boolean): true: nothing changed; repeat the call with confirm: true to do it.wouldInvite(string[]): preview of an invite: the addresses that would be emailed.level(string): preview of an invite: the level they would get.wouldMakeLinkOn(boolean): preview of a link turned on.note(string)members(object[])invitations(object[])results(object[])shareUrl(string | null)linkOn(boolean)removed(boolean)left(boolean)ended(boolean)
Example
curl -X POST "https://api.roma.app/api/v1/items/<id>/sharing" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"action":"members"}'
Items
GET /items
List and filter items · Read-only · MCP tool list_items
List, 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 and whoever owns it (a list shared with the person too): 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.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | no | One list's items: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list). Omit for the Tasks set. |
changedSince | string | no | An ISO 8601 instant (exclusive), or the nextChangedSince of the previous read verbatim. The changes feed for a worker that polls: every item of the list (or of the person's own lists that keep the task columns, trashed and archived ones included) whose record moved after it — edits, completions, archives, restores, deletions — oldest change first, the deleted ones as deleted tombstones, then hasMore and nextChangedSince to pass next time. Items shared with the person are not in the feed (list_items without changedSince reads them). query is refused beside it; the other filters and sort do not apply. |
ids | string[] | no | Specific item ids to fetch (the other filters still apply). |
delegatedTo | string | no | Only the items delegated to one of the person's agents (its record in the Delegate cell): "me" for the agent record this call is made under (the connected app's own record, or the record register_agent bound), else the agent's name or id. On a sign-in that carries several agents (ChatGPT and its Dot), "me" is all of them and guidance names them; pass your own name for your items alone. The work handed to an agent, for one that reads on its own schedule. (up to 80 characters) |
assignedTo | string | no | The old name of delegatedTo, taken the same way; prefer delegatedTo. (up to 80 characters) |
agentName | string | null | no | With delegatedTo "me": Who is calling, when this sign-in carries several agents (several Grok Bots of one account; ChatGPT and a Dot): your own agent's name, or its agentId. Pass it on every call. A sign-in or key with one agent is that agent whatever this says. |
query | string | no | Free-text search across title and body. |
taskStatus | string[] | no | Filter to these statuses, on lists that keep one — each a status id of the list's Status property (todo, inProgress, completed on every list that keeps one; backlog, inReview, canceled and the list's own ids where list_lists shows them). A done-stage status completes the item. A stage word (open, active, done) stands for every status of that stage on every list. Omit for the default: every status that is not done. |
dueAfter | string | no | ISO 8601 instant — only items due on/after this (inclusive). |
dueBefore | string | no | ISO 8601 instant — only items due before this (exclusive). Today = dueAfter today 00:00 local, dueBefore tomorrow 00:00 local; overdue = dueBefore today 00:00 alone. |
createdAfter | string | no | ISO 8601 instant — only items created on/after this. |
createdBefore | string | no | ISO 8601 instant — only items created before this (exclusive). |
updatedAfter | string | no | ISO 8601 instant — only items last edited on/after this. A poll that wants deletions too uses changedSince instead. |
updatedBefore | string | no | ISO 8601 instant — only items last edited before this (exclusive). |
completedAfter | string | no | ISO 8601 instant — only items completed on/after this. Implies completed items unless taskStatus says otherwise. |
completedBefore | string | no | ISO 8601 instant — only items completed before this (exclusive). |
sort | "due" | "created" | "updated" | "completed" | no | Row order. Default 'due' (due date, then creation); a timestamp sort returns newest first. |
limit | integer | no | Max results (default 50). (1 to 200) |
includeImageUrls | boolean | no | true additionally returns a short-lived signed url per attachment so the images can be viewed. Off by default. |
Returns 200
count(number)listId(string | null)listName(string | null)listIcon(string | null): The list's own icon, an emoji, when it has one; null for the Tasks set.properties(object[]): The list's own properties, on a read of one list that has some.items(object[])deleted(object[]): With changedSince: the items deleted since, as tombstones.serverTime(string): With changedSince: the server's clock when this read began.hasMore(boolean): With changedSince: more changed thanlimit; continue withnextChangedSince.nextChangedSince(string): With changedSince: what to pass as the next call's changedSince, verbatim (an instant, or the last row's stamp and id while more is pending).guidance(string): One line about this read, when there is one: with delegatedTo "me" on a sign-in that carries several agents, which agents the rows belong to; or why the read is empty.links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.
Example
curl -X GET "https://api.roma.app/api/v1/items" \
-H "Authorization: Bearer roma_…"
POST /items
Create items on a list, many in one call · Adds data · MCP tool create_items
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; a person value — who the item is for, Assigned to or any person column — is a member's name or id from the list's people in list_lists; an agent's name written there is taken as the item's delegate, the same as delegate, never as an assignee; a name nobody on the list answers to is refused, never added). An entry's delegate names the one agent whose turn the item is: "Operator" (Roma's own first turn), or one of the user's own agents by name or id from the list's delegates, which hands it the item and wakes it; "none" makes the item with no delegate; omitted, the list's own rule decides (Operator by default; a shared list has no default delegate). An item you make for the person gets no delegate unless you pass one. 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.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | no | 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). Omit for the Tasks list. |
items | object[] | yes | Every item to create, in one call. (up to 100 items) |
agentName | string | null | no | Who is calling, when this sign-in carries several agents (several Grok Bots of one account; ChatGPT and a Dot): your own agent's name, or its agentId. Pass it on every call. A sign-in or key with one agent is that agent whatever this says. |
matchOn | string[] | null | no | 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. |
enrich | boolean | null | no | 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. |
Returns 201
listId(string)listName(string)listIcon(string | null): The list's own icon, an emoji, when it has one.properties(object[]): The list's own properties, when it has some.items(object[])added(number): Items inserted by this call.links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.mergedIds(string[]): Existing items an entry was merged into through matchOn.existing(object[])failed(object[])unknownKeys(string[])imagesAttached(number)imageFailures(object[])job(object): Present when the batch was past the inline threshold (more than 20 entries or 2 MB in one call): the call was accepted and stored as a job, nothing is written yet, and the entries land in the background a few at a time. Poll get_job withjob.idfor progress; the other fields of the result are empty.
Example
curl -X POST "https://api.roma.app/api/v1/items" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"items":[{}]}'
PATCH /items
Update items, many in one call · Updates or removes existing data · MCP tool update_items
Update 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. The body is the result of the work: edit it as your work lands — the findings, the draft, the numbers, a ticked step — no permission needed; every body write is logged with what it did and can be put back by the person. Every item whose body you change takes message — the brief message for the person, at most 420 characters, what changed and what you need — and may take agentDetail, the part for agents: only what the edit itself does not say — the why, what you considered and rejected, the sources, the doubts — never the text you wrote (the log holds it) and never the message again, up to 20000 characters; a detail that mostly repeats the edit or the message is dropped and the item's warning says so. A body change without message is refused whole (messageRequired) and writes nothing. The message is posted in the item's thread under your name, carries the edit, and the edit's log line carries the message. A change to the title, the status, a date or a value needs no message. Roma's summary of the item — its own panel above the body — is Roma's, read and never written. values MERGE into the item (only the properties sent change; "" clears one; an unknown property is an error naming the valid ones). Assigning is a person value: "assign these to Mara" is each item's values carrying the list's person property — Assigned to, assignedTo, where the list has it — with her name or id from the list's people in list_lists, many items in one call; a name nobody on the list answers to is refused with the names that are, and "" unassigns; an agent's name written into a person cell is taken as the item's delegate, the same as delegate, never as an assignee. Delegating is the item's delegate: "hand these to ChatGPT" is each item's delegate carrying one of the user's own agents by name or id from the list's delegates in list_lists, which hands it the item and wakes it (a new delegate cancels the previous one's hand-off); "Operator" hands it to Roma's own operator; "none" removes the delegate. An agent's hand-off to another agent is an entry that carries delegate and nothing else that changes the item (a message is fine). A delegate naming the agent already in the Delegate cell beside another change is no hand-off: the other fields are written and nobody is woken. While the agent the item was last handed to still has it (it is working, waiting for the person, or waiting for its computer), naming it again changes nothing and the item's answer says who has it (notHandedOver, code handoffAlreadyHeld). Once that agent returned the item, handing it the item again is a new round and wakes it again; that holds for the agent already in the Delegate cell too, so never clear the delegate first to hand an item again (that is refused with handoffAlreadyHeld). The same holds once it worked on the item and then went quiet. An agent that never started on the item, or whose run failed, cannot be handed it again by an agent (handoffAlreadyHeld): only the person can. Three hand-offs by agents to the same agent on one item, and ten by agents in all, are refused with handoffLimitReached. A refused hand-off writes nothing. Only the person lifts a limit, in Roma: tell them to open the item in Roma and set Delegate to that agent themselves (an agent already in the cell is picked there again); their yes in your chat does not count. following (on an item, or on the call for every item) follows or mutes the item's edits and chat for the user alone. imageUrls add images (clearImages: true drops the old ones first). taskStatus, dueAt, reminderAt and muteReminder apply only on a list that keeps them: a due date is a day, or a local time when one was stated, which also arms a reminder at that moment; reminderAt arms a reminder on a day without touching the date; muteReminder turns it off; dueAt "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. An agent that holds a task (its record in the Delegate cell) gives it back with handoff: "returned" on the item, on the same call that writes its last result, with the message that call carries; the agent stays in the cell, the task reads Done, and the answer's returnedTo names who has it now. An agent never clears itself from the cell.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
items | object[] | yes | Every item to update, in one call. (up to 200 items) |
agentName | string | null | no | For an agent record: which of the agents on this sign-in or key is writing, when it carries several (ChatGPT and a Dot share one sign-in; several records on one key): pass your own record's name on every call. A sign-in or key with one record writes as that record whatever this says. Otherwise how a key-bound caller with no record is named on the message a body change posts (default "Your agent"). |
mode | "prepend" | "append" | "replace" | "insertAfter" | null | no | Legacy: how each item's body merges: 'append' (default, at the bottom), 'prepend' (at the top), 'insertAfter' (right after the line named in anchor), or 'replace' (swap the whole body — only when the user explicitly asked to rewrite it; requires confirmReplace: true). |
anchor | string | null | no | For mode 'insertAfter' only: a verbatim snippet of the existing line to insert after. Errors if not found. |
confirmReplace | boolean | null | no | Required (true) for mode 'replace': confirms the user explicitly asked to swap the WHOLE body, deleting everything in it. Never pass it on the user's behalf without that explicit ask. |
taskStatus | string | null | no | On a list that keeps a status: a status id of the list's Status property (todo, inProgress, completed on every list that keeps one; backlog, inReview, canceled and the list's own ids where list_lists shows them). A done-stage status completes the item. Applies to every item in the call. Status transitions report progress. |
dueAt | string | null | no | On a list that keeps a due date, for every item in the call: YYYY-MM-DD for a day the person named with no time (the usual case; nothing rings); YYYY-MM-DDTHH:MM in their local time when they stated a time, which also arms a push reminder at that moment. An instant with a zone (2026-10-28T09:00:00Z) is read as the day it falls on in their zone unless hasDueTime is true. A reminder already armed follows a moved day. "none" removes the due date with its time and reminder. |
hasDueTime | boolean | null | no | With a dueAt that carries a zone: true when its time of day is meant (the due is that moment and the reminder is armed), false to keep the day alone. Not needed for the two plain shapes. |
reminderAt | string | null | no | Arms a reminder without changing the visible due date, for every item in the call: YYYY-MM-DD (that day at the person's default reminder hour) or YYYY-MM-DDTHH:MM in their local time. An undated item is dated that day. A moment already passed arms nothing. Not beside dueAt "none" or muteReminder. |
muteReminder | boolean | null | no | true turns the reminder off and leaves the due date and its time as they are, for every item in the call. Not beside reminderAt. |
archived | boolean | null | no | true sets the item(s) aside (hidden from every list, kept and reversible); false brings them back. |
favorited | boolean | null | no | true pins the item(s) in the app's Favorites; false unpins them. |
following | object | null | no | The user's own following of every item's edits and chat in the call: each half "follow" or "mute". An item's own following wins for that item. Omit to leave it. |
Returns 200
updated(number)items(object[])imagesAttached(number)imageFailures(object[])links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.job(object): Present when the batch was past the inline threshold (more than 20 entries or 2 MB in one call): the call was accepted and stored as a job, nothing is written yet, and the entries land in the background a few at a time. Poll get_job withjob.idfor progress; the other fields of the result are empty.
Example
curl -X PATCH "https://api.roma.app/api/v1/items" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"items":[{"itemId":"<itemId>"}]}'
DELETE /items
Delete items into the trash · Updates or removes existing data · MCP tool delete_items
Delete 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. An item inside a list shared with the user deletes as the app lets them, under its owner with the user named; ids the user may not delete — not theirs, or shared with them one item at a time — are reported under refused with the reason, and the rest still delete.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
itemIds | string[] | yes | The items' ids. Up to 50 per call. (up to 50 items) |
Returns 200
deleted(number)items(object[])refused(string[])refusals(object[])job(object): Present when the batch was past the inline threshold (more than 20 entries or 2 MB in one call): the call was accepted and stored as a job, nothing is written yet, and the entries land in the background a few at a time. Poll get_job withjob.idfor progress; the other fields of the result are empty.
Example
curl -X DELETE "https://api.roma.app/api/v1/items" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"itemIds":["<itemIds>"]}'
POST /items/query
Filter, sort, count or sum the items of one list · Read-only · MCP tool query_items
Filter, 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.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | yes | The list to query: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list). |
where | object[] | null | no | Filter clauses, AND-combined. Omit for every item. |
sort | object | null | no | Sort order. Omit for the list's default (newest first). |
mode | "list" | "count" | "sum" | null | no | 'list' (default) returns matching items; 'count' how many match; 'sum' totals sumPropertyId across matches. |
sumPropertyId | string | null | no | For mode 'sum': the numeric property to total (its stable id or name). |
createdAfter | string | null | no | ISO 8601 instant — items added on/after this. |
createdBefore | string | null | no | ISO 8601 instant — items added before this (exclusive). |
updatedAfter | string | null | no | ISO 8601 instant — items last edited on/after this. A read that repeats on a schedule passes the instant of its previous read here, or uses list_items' changedSince, which also carries deletions. |
updatedBefore | string | null | no | ISO 8601 instant — items last edited before this (exclusive). |
includeArchived | boolean | null | no | true also includes archived items (hidden from every list by default), so one can be brought back with update_items. |
limit | integer | null | no | mode 'list': max items per page (default 50). |
offset | integer | null | no | mode 'list': items to skip — page through a big list with offset + limit until hasMore is false. |
includeImageUrls | boolean | null | no | mode 'list': true additionally returns a short-lived signed url per attachment. |
Returns 200
mode("list" | "count" | "sum")listId(string)listName(string)listIcon(string | null): The list's own icon, an emoji, when it has one.count(number): How many items match.sum(number)sumPropertyId(string)properties(object[])items(object[])offset(number)hasMore(boolean)
Example
curl -X POST "https://api.roma.app/api/v1/items/query" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"listId":"<listId>"}'
POST /items/move
Move items onto another list · Updates or removes existing data · MCP tool move_items
Move 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. An item inside a list shared with the user moves as far as the app lets them: out onto one of their own lists (it becomes theirs, and everyone in the shared list loses it), or into another shared list they are in; such a move changes who can reach the item, so the first call answers a preview (accessChanges, the app's own question) and moves nothing until the repeat with acknowledgeDataLoss: true. An item shared with the user one item at a time stays its owner's to move: it is reported under refused with the reason, never moved.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
itemIds | string[] | yes | Ids of the items to move. (up to 100 items) |
listId | string | yes | The destination list: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list). |
acknowledgeDataLoss | boolean | null | no | true ONLY on a repeat call, after a preview reported values the destination list has no place for, or people who will gain or lose access, and you told the user what will happen. |
Returns 200
preview(boolean)listId(string)listName(string | null)items(object[])droppedValues(object[])accessChanges(object[])refused(string[])refusals(object[])
Example
curl -X POST "https://api.roma.app/api/v1/items/move" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"itemIds":["<itemIds>"],"listId":"<listId>"}'
GET /items/{id}
One item with its body, values and list · Read-only · MCP tool get_item
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
id: 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
| Parameter | Type | Required | Description |
|---|---|---|---|
includeImageUrls | boolean | no | true additionally returns a short-lived signed url per attachment so the images can be viewed. Off by default. |
includeImages | boolean | no | 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. |
includeFiles | boolean | no | true additionally returns the words of the files in the body — the [name](roma://attachment/…) lines: a PDF's text, a scanned PDF transcribed, a text file as it is — as text blocks after the item (up to five files and 30,000 characters, in body order, each under a line naming it). The way to read a lease or a schedule attached to the item. Off by default. |
Returns 200
id(string)identifier(string | null): 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 | null)body(string | null): 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-bodyrewritenames it asbaseVersion.taskStatus(string | null): On a list that keeps a status.dueAt(string | null): On a list that keeps a due date: the instant stored; a day when hasDueTime is false.hasDueTime(boolean | null): Whether dueAt's time of day is meant; false for a day.reminderAt(string | null): When the reminder rings, as an instant; null for none.completedAt(string | null)values(object): The item's values keyed by property id; a select value is an option id.cells(object of string): 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;editablesays what update_items admits on it.editable("all" | "titleAndBody"): On a row shared with the person:all— every field but the owner's own reminder, repeat and favorite, whether the item was shared with them one by one or through a list; update_items refuses the owner's own fields by name.listId(string | null)listName(string | null)listIcon(string | null): The list's own icon, an emoji, when it has one.expertId(string | null): 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.summary(string | object)summarySeq(number | null): The number of the log line the summary rests on, so a reader of the item in Roma can tell a summary that lags its log from one that is current.synthesizedAt(string | null): When Roma last wrote the summary.createdAt(string | null)updatedAt(string | null)editedAt(string | null)archivedAt(string | null)recordingStatus(string)attachments(object[])bodyImages(object[]): The pictures the body shows (), 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.guidance(string): 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 | null): 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.list(object): Present when the item's list carries standing instructions: they apply to every item on it, this one included.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.webUrl(string): The item's page in Roma, to open in a browser.appUrl(string): The item in the Roma Mac app: the app's own link scheme (yamo://artifacts/:id; yamo-staging:// against staging).transcript(string)recording(object)taskCandidates(object[])
Example
curl -X GET "https://api.roma.app/api/v1/items/<id>" \
-H "Authorization: Bearer roma_…"
GET /items/{id}/versions
The version history of an item, newest first · Read-only · MCP tool list_versions
List 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. Versions are kept for the item's life; a long history pages by before.
Path
id: The item's or the expert's id (from list_items, search, get_item or list_experts).
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | null | no | Entries per page, newest first (default 50, at most 200). |
before | string | null | no | Only the entries from before this instant (ISO 8601): the createdAt of the last entry seen, for the page before it. |
Returns 200
id(string)hint(string)versions(object[])
Example
curl -X GET "https://api.roma.app/api/v1/items/<id>/versions" \
-H "Authorization: Bearer roma_…"
GET /items/{id}/versions/{versionId}
One earlier version of an item's body, with the line changes to the next state · Read-only · MCP tool get_version
Read 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.
Path
id: The item's or the expert's id.versionId: The version to read, from list_versions or a log line's versionId.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
diffAgainst | string | null | no | "current" (default) or another version id of the same item: what the snapshot is compared with. |
includeBody | boolean | null | no | false leaves the body out and answers the entry and the diff alone (default true). |
Returns 200
id(string)version(object)markdown(string)values(object | null)diff(object)
Example
curl -X GET "https://api.roma.app/api/v1/items/<id>/versions/<versionId>" \
-H "Authorization: Bearer roma_…"
GET /items/{id}/blame
Who wrote each line of an item's body as it stands, newest writer per line · Read-only · MCP tool get_blame
Who 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.
Path
id: The item's id (from list_items, search or get_item).
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fromLine | integer | null | no | The first line of the window (default 1). |
toLine | integer | null | no | The last line of the window (default the body's last line). |
Returns 200
id(string)bodyVersion(string): The stamp of the body the runs describe; update_items' rewrite takes it as baseVersion.lines(string[])ranges(object[])versionsWalked(number)truncated(boolean)
Example
curl -X GET "https://api.roma.app/api/v1/items/<id>/blame" \
-H "Authorization: Bearer roma_…"
POST /items/{id}/versions/{versionId}/restore
Restore an item's body to an earlier version · Updates or removes existing data · MCP tool restore_version
Restore 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.
Path
id: The item's or the expert's id.versionId: The version to restore, from list_versions.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
acceptLaterEdits | boolean | null | no | true only after the person said yes to losing the edits made in Roma after that version, the ones the needsConfirmation answer named. Omit on the first call. |
Returns 200
restored(boolean)id(string)title(string | null)needsConfirmation(boolean)laterEdits(object[])hint(string)
Example
curl -X POST "https://api.roma.app/api/v1/items/<id>/versions/<versionId>/restore" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{}'
POST /uploads
Pre-signed slots for image bytes · Adds data · MCP tool create_image_upload
Get 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.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
mimeType | "image/png" | "image/jpeg" | "image/heic" | "image/webp" | yes | The image type you will upload (all slots in one call share it). |
count | integer | no | How many upload slots (default 1). (1 to 10) |
Returns 201
uploads(object[])maxBytes(number)validForSeconds(number)
Example
curl -X POST "https://api.roma.app/api/v1/uploads" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"mimeType":"image/png"}'
GET /jobs/{id}
The progress of a queued bulk write: how many entries landed, which failed and why · Read-only · MCP tool get_job
Read 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.
Path
id: The job's id, from thejobblock a bulk write answered with.
Returns 200
id(string)tool(string)status("queued" | "running" | "done" | "failed")total(number)done(number): Entries that landed (an entry matched to an existing item counts here).failed(number)listId(string | null)error(string | null): Why the whole job stopped, when it failed.createdAt(string)startedAt(string | null)finishedAt(string | null)entries(object[]): The entries that have run so far, in order, up to the first 500.links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.
Example
curl -X GET "https://api.roma.app/api/v1/jobs/<id>" \
-H "Authorization: Bearer roma_…"
Chats
GET /items/{id}/messages
Recent messages in an item's chat · Read-only · MCP tool read_chat_messages
Read 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. On a shared item (shared on its own or through its list) the chat is its Thread, the one conversation the owner and every member see, so you read what the members said too. 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. A message from an agent may carry agentDetail, the part meant for agents — what the edit itself does not say: the why, what was considered and rejected, the sources, the doubts — and edit, the body edit it accompanies (the log line, its seq and the snapshot); a person's message carries neither, and Roma's own replies carry no agentDetail. The edit's text itself is the log's: read_log. A conversation bound to no item (the person's main chat, a list's chat) is read by conversationId, the id a mention's delivery carried.
Path
id: The item's id, or a Roma link to it (roma.app/artifacts/<id>). One of artifactId / conversationId.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
conversationId | string | no | The conversation's id, for a chat bound to no item (the main chat, a list's chat): the conversation.id a mention's delivery carried. One of artifactId / conversationId. |
since | string | no | ISO 8601 instant. Only messages created after it are returned, oldest first: the createdAt of the last message you saw. |
limit | integer | no | Max messages (default 20). (1 to 50) |
Returns 200
sessionId(string | null)messages(object[])truncated(boolean)
Example
curl -X GET "https://api.roma.app/api/v1/items/<id>/messages" \
-H "Authorization: Bearer roma_…"
POST /items/{id}/messages
Post a message into an item's chat as an agent · Updates or removes existing data · MCP tool post_chat_message
Post a message into an item's thread as the calling agent: a post for an action taken outside Roma with its link, or the one question the work is blocked on (a body change's message is the post for the work itself), at most 420 characters, saying what changed and what is needed from the person. A second post before the person has replied, the status has changed or 30 minutes have passed is refused. agentDetail, the part for agents behind the message, is for what the message does not say — the why, what was considered and rejected, the sources, the doubts — never the message again (a detail that mostly repeats it is dropped and warning says so). A body change posts its own message through update_items (message on the item), never here. On a shared item (shared on its own or through its list) the post lands in its Thread, where the owner and every member read it. The user sees it on every device as an unread reply on the item and as an Updates row under your name, and the agent cannot take it back, so a post per step reads as noise; a post the item's own body asks you for is the person's ask and is wanted. Set needsInput when the work is blocked on their answer. The same messageKey posted twice lands once. The person is offered Reply on your post only when you will read it: a live trigger wakes you by this agentName (manage_triggers, action create, with agentName), or you pass readsReplies: true because you read this chat again on your next run (read_chat_messages with since). Otherwise the post is a notification they cannot answer, so do not ask a question in it. The answer's listening says whether a reply would wake you at once. An agent with a record (a connected app, or the record register_agent bound) posts under the record's name whatever agentName says, and the person's Reply wakes it through its own door; only where one sign-in or key carries several agents does agentName say which of them posts. A mention in a chat bound to no item (the person's main chat, a list's chat) is answered there: pass the conversation.id the delivery carried as conversationId instead of an item. mentions addresses members of the item (or of the list a list room belongs to) by name or user id: a mentioned member gets a mention notification even when they muted the chat, so mention only who the message is for; a name nobody on it answers to is refused naming who is. A mention not already written into the message as a [@Name](roma://person/<id>) link is appended to its end so every client shows who was addressed, and the length cap counts the appended chips (tooLong). The operator is never mentioned here: the person addresses the operator in a room, not an agent.
Path
id: The item's id, or a Roma link to it (roma.app/artifacts/<id>). One of artifactId / conversationId.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
conversationId | string | no | The conversation's id, for a post into a chat bound to no item (the main chat, a list's chat): the conversation.id a mention's delivery carried. One of artifactId / conversationId. |
mentions | string[] | no | Members to address, by name or user id, at most 10: each gets a mention notification even when they muted the chat. Never "operator". Only who the message is for. (up to 10 items) |
message | string | yes | The message for the person, as Markdown, at most 420 characters including the mention chips appended for mentions; what does not fit goes to agentDetail. The message is plain sentences, as a chat is: Markdown for a link, inline code or a short list, and bold only on a phrase inside a sentence; never a heading and never a whole line in bold: a message this short is one section, and the thread draws either as a title. (up to 420 characters) |
agentDetail | string | no | Optional: the part for agents — only what the message does not say: the why, what you considered and rejected, the sources, the doubts, what is left — any style, up to 20000 characters, read by the next agent behind the message in Roma. Never the message again: a detail that mostly repeats it is dropped and warning says so. (up to 20000 characters) |
agentName | string | no | How a caller with no record is named in the chat (default "Your agent"). For an agent record: which of the agents on this sign-in or key is posting, when it carries several (ChatGPT and a Dot share one sign-in; several records on one key): pass your own record's name on every call. A sign-in or key with one record posts as that record whatever this says. (up to 60 characters) |
needsInput | boolean | no | True when the message is a question the work waits on. |
readsReplies | boolean | no | True when you read this chat again on your next run, so the person may answer here even with no trigger waking you. |
messageKey | string | no | Idempotency key: a retry with the same key updates the same message. (up to 120 characters) |
Returns 201
id(string)sessionId(string)createdAt(string)listening(boolean): Whether a reply from the person would wake this agent through a trigger. False: the reply waits for the agent's next run.mentioned(object[]): The membersmentionsaddressed, as resolved.warning(string): The message landed and something beside it did not: agentDetail dropped as a copy of the message (detailDropped).
Example
curl -X POST "https://api.roma.app/api/v1/items/<id>/messages" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"message":"<message>"}'
GET /items/{id}/log
The item's log, Roma's own record: every change and post, with who made it · Read-only · MCP tool read_log
Read 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'.
Path
id: The item's id, its ID (TASK-12) or a Roma link. One of itemId / listId.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | no | The list's id, for the list's own log. One of itemId / listId. |
since | integer | no | The seq of the last line you saw: only lines after it, oldest first. (-9007199254740991 to 9007199254740991) |
beforeSeq | integer | no | Paging backwards without since: lines with a seq below this one. (-9007199254740991 to 9007199254740991) |
limit | integer | no | Max lines (default 50). (1 to 200) |
kinds | string[] | no | Only these kinds: created, updated, moved, deleted, undeleted, restored, rewritten, posted, noted, joined, left, handoff, returned, released. |
Returns 200
entries(object[])nextBeforeSeq(number | null)truncated(boolean)
Example
curl -X GET "https://api.roma.app/api/v1/items/<id>/log" \
-H "Authorization: Bearer roma_…"
GET /items/{id}/wait
Hold until something new lands on the item's log, at most 25 seconds · Read-only · MCP tool wait_for_item
Hold 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.
Path
id: The item's id, its ID (TASK-12) or a Roma link.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
since | integer | no | The seq of the last log line you saw: only lines after it count. Default: the newest seq when the call starts, so only what lands from now on. (-9007199254740991 to 9007199254740991) |
timeoutSeconds | integer | no | How long to hold, 1 to 25 seconds (default 25). (1 to 25) |
until | "any" | "return" | "post" | no | What ends the wait: "any" (default), "return", or "post". |
agentName | string | null | no | Who is calling, when this sign-in carries several agents (several Grok Bots of one account; ChatGPT and a Dot): your own agent's name, or its agentId. Pass it on every call. A sign-in or key with one agent is that agent whatever this says. |
Returns 200
lines(object[])agentState(any | null): The task's hand-off state at that moment (as get_item answers it), null when no agent holds it.nextSince(number): Pass assinceon the next call.timedOut(boolean)busy(boolean): True when another wait of yours on this item was already running: this call answered at once.
Example
curl -X GET "https://api.roma.app/api/v1/items/<id>/wait" \
-H "Authorization: Bearer roma_…"
Search
GET /search
Search items and lists · Read-only · MCP tool search
Search the user's Roma workspace — their items (tasks, notes, the rows of every list they keep) and their lists, and what others shared with them (an item shared on its own, a list they joined and every item on it, each marked isSharedWithMe) — 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.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | yes | Natural-language query — what the user is trying to find, in their words. |
limit | integer | no | Max results (default 10). (1 to 20) |
after | string | no | Only items CREATED on/after this ISO 8601 timestamp. Use when scoping by when it was saved ("last week", "in March"). |
before | string | no | Only items CREATED before this ISO 8601 timestamp (exclusive). Pair with after to bound a window. |
Returns 200
count(number)results(object[])
Example
curl -X GET "https://api.roma.app/api/v1/search" \
-H "Authorization: Bearer roma_…"
GET /lists/{id}/grep
Find the lines of a list's item bodies that match a pattern, with their block handles · Read-only · MCP tool grep_items
Find 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.
Path
id: The list to grep: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list).
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
pattern | string | yes | What to find: a literal, or a regular expression with regex: true. (up to 200 characters) |
regex | boolean | null | no | true reads the pattern as a regular expression (default false: a literal). |
caseSensitive | boolean | null | no | true matches case exactly (default false). |
context | integer | null | no | Lines of context on each side of a hit (default 1, at most 3). |
limit | integer | null | no | Items answered at most (default 20); hasMore says when the list holds more matching items. |
matchesPerItem | integer | null | no | Lines answered per item at most (default 5); moreMatches says when the body holds more. |
Returns 200
listId(string)listName(string)count(number): Items answered.hasMore(boolean)items(object[])
Example
curl -X GET "https://api.roma.app/api/v1/lists/<id>/grep" \
-H "Authorization: Bearer roma_…"
Trash
GET /trash
What is in the trash · Read-only · MCP tool list_deleted
The 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.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
type | "item" | "list" | no | Only this kind. Omit for both. |
limit | integer | no | Max entries per kind (default 25). (1 to 100) |
Returns 200
count(number)items(object[])
Example
curl -X GET "https://api.roma.app/api/v1/trash" \
-H "Authorization: Bearer roma_…"
POST /trash/restore
Restore one item or list from the trash · Adds data · MCP tool restore_deleted
Bring 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.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
type | "item" | "list" | yes | The entry's type, as list_deleted reported it. |
id | string | yes | The deleted item's or list's id. |
Returns 200
restored(boolean)alreadyLive(boolean)type(string)id(string)title(string | null)restoredItems(number)movedToDefaultList(boolean)
Example
curl -X POST "https://api.roma.app/api/v1/trash/restore" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"type":"item","id":"<id>"}'
Automations
GET /automations
List automations · Read-only · MCP tool list_automations
List 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.
Returns 200
count(number)automations(object[])
Example
curl -X GET "https://api.roma.app/api/v1/automations" \
-H "Authorization: Bearer roma_…"
GET /automations/{id}
One automation in full, its steps included · Read-only · MCP tool get_automation
Read 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.
Path
id: The automation's id (from list_automations or get_context).
Returns 200
id(string)name(string)status(string)when(string)nextRunAt(string | null)steps(string): The steps as written, Markdown; empty when there are none.webUrl(string)
Example
curl -X GET "https://api.roma.app/api/v1/automations/<id>" \
-H "Authorization: Bearer roma_…"
GET /automations/{id}/runs
Recent runs of an automation · Read-only · MCP tool get_automation_runs
Read 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.
Path
id: The automation's id (from list_automations or get_context).
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | no | How many runs, newest first (default 5, max 20). (1 to 20) |
Returns 200
automation(object)runs(object[])
Example
curl -X GET "https://api.roma.app/api/v1/automations/<id>/runs" \
-H "Authorization: Bearer roma_…"
POST /automations/{id}/run
Start an automation now · Updates or removes existing data · MCP tool run_automation
Start 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.
Path
id: The automation's id (from list_automations or get_context).
Returns 200
id(string)name(string)runId(string)status(string)
Example
curl -X POST "https://api.roma.app/api/v1/automations/<id>/run" \
-H "Authorization: Bearer roma_…"
Triggers
GET /triggers
The triggers with their last delivery, and the catalogue of events · Updates or removes existing data · MCP tool manage_triggers
The 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 agent that calls, so the user's replies to its posts are delivered too. A trigger you make for an agent is made for your own agent: naming another agent, by agentId or by agentName, is refused, and one agent has one trigger (a second create is refused with the triggerId to update). The transport never changes on update; delete and create again. Twenty per account. A trigger that belongs to another of the user's agents is theirs alone: you can list it, and only that agent or the user changes or deletes it. 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).
Returns 200
triggers(object[]): For list.events(object[]): For list: the catalogue.trigger(object): For create and update.secret(string | null): For create: the signing secret, this once; null for a poll trigger.deleted(boolean): For delete.
Example
curl -X GET "https://api.roma.app/api/v1/triggers" \
-H "Authorization: Bearer roma_…"
POST /triggers
Make a trigger: which events fire it, a filter, where the event goes · Updates or removes existing data · MCP tool manage_triggers
The 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 agent that calls, so the user's replies to its posts are delivered too. A trigger you make for an agent is made for your own agent: naming another agent, by agentId or by agentName, is refused, and one agent has one trigger (a second create is refused with the triggerId to update). The transport never changes on update; delete and create again. Twenty per account. A trigger that belongs to another of the user's agents is theirs alone: you can list it, and only that agent or the user changes or deletes it. 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).
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
triggerId | string | no | For update and delete: the trigger's id (from list). |
name | string | no | For create (required) or update: what it wakes: "Claude Code on the Mac", "Codex for testing". (up to 80 characters) |
events | "item.created" | "item.updated" | "item.statusUpdated" | "item.moved" | "item.deleted" | "item.restored" | "list.created" | "list.updated" | "list.deleted" | "list.restored" | "item.delegated" | "message.posted" | "automation.completed"[] | no | For create (required) or update: which events fire it. |
filter | object | null | no | For create or update: what narrows an event to this trigger; on update null clears it. |
transport | "webhook" | "poll" | no | For create: webhook (default, needs url) or poll (no address; read with the deliveries route). |
url | string (uri) | no | For a webhook: the https address Roma POSTs to (create), or the new one (update). |
secret | string | no | For a webhook on create: your own whsec_ secret (base64, 32 bytes); minted when absent. (up to 200 characters) |
headers | object of string | no | For a webhook: extra request headers Roma sends on every POST to the user's agent, as the agent's own address requires. Stored, never read back; on update they replace the old ones. |
agentName | string | no | The agent this trigger wakes: yourself, exactly as you name yourself in post_chat_message ("Claude Code"). The trigger is then made for your own agent, and the person's replies to your posts fire it too. Another agent's name is refused. On update, empty clears it. Where several agents share one sign-in (every Grok Bot of one account) it says who is calling: your own name, or your own agentId. You change and delete only your own. (up to 60 characters) |
agentId | string | no | The agent RECORD this trigger wakes: your own. The items delegated to it (item.delegated) and the replies to its posts fire it. Leave it out or pass your own: another agent's id is refused. A trigger on item.delegated or message.posted that names no agent is made for your own agent; when your sign-in carries several agents, say which one. On update, empty clears it. (up to 60 characters) |
paused | boolean | no | For update: true pauses, false resumes. |
Returns 201
triggers(object[]): For list.events(object[]): For list: the catalogue.trigger(object): For create and update.secret(string | null): For create: the signing secret, this once; null for a poll trigger.deleted(boolean): For delete.
Example
curl -X POST "https://api.roma.app/api/v1/triggers" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{}'
PATCH /triggers/{id}
Rename a trigger, change its events, filter, address or headers, pause or resume it · Updates or removes existing data · MCP tool manage_triggers
The 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 agent that calls, so the user's replies to its posts are delivered too. A trigger you make for an agent is made for your own agent: naming another agent, by agentId or by agentName, is refused, and one agent has one trigger (a second create is refused with the triggerId to update). The transport never changes on update; delete and create again. Twenty per account. A trigger that belongs to another of the user's agents is theirs alone: you can list it, and only that agent or the user changes or deletes it. 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).
Path
id: For update and delete: the trigger's id (from list).
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | no | For create (required) or update: what it wakes: "Claude Code on the Mac", "Codex for testing". (up to 80 characters) |
events | "item.created" | "item.updated" | "item.statusUpdated" | "item.moved" | "item.deleted" | "item.restored" | "list.created" | "list.updated" | "list.deleted" | "list.restored" | "item.delegated" | "message.posted" | "automation.completed"[] | no | For create (required) or update: which events fire it. |
filter | object | null | no | For create or update: what narrows an event to this trigger; on update null clears it. |
transport | "webhook" | "poll" | no | For create: webhook (default, needs url) or poll (no address; read with the deliveries route). |
url | string (uri) | no | For a webhook: the https address Roma POSTs to (create), or the new one (update). |
secret | string | no | For a webhook on create: your own whsec_ secret (base64, 32 bytes); minted when absent. (up to 200 characters) |
headers | object of string | no | For a webhook: extra request headers Roma sends on every POST to the user's agent, as the agent's own address requires. Stored, never read back; on update they replace the old ones. |
agentName | string | no | The agent this trigger wakes: yourself, exactly as you name yourself in post_chat_message ("Claude Code"). The trigger is then made for your own agent, and the person's replies to your posts fire it too. Another agent's name is refused. On update, empty clears it. Where several agents share one sign-in (every Grok Bot of one account) it says who is calling: your own name, or your own agentId. You change and delete only your own. (up to 60 characters) |
agentId | string | no | The agent RECORD this trigger wakes: your own. The items delegated to it (item.delegated) and the replies to its posts fire it. Leave it out or pass your own: another agent's id is refused. A trigger on item.delegated or message.posted that names no agent is made for your own agent; when your sign-in carries several agents, say which one. On update, empty clears it. (up to 60 characters) |
paused | boolean | no | For update: true pauses, false resumes. |
Returns 200
triggers(object[]): For list.events(object[]): For list: the catalogue.trigger(object): For create and update.secret(string | null): For create: the signing secret, this once; null for a poll trigger.deleted(boolean): For delete.
Example
curl -X PATCH "https://api.roma.app/api/v1/triggers/<id>" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{}'
DELETE /triggers/{id}
Delete a trigger · Updates or removes existing data · MCP tool manage_triggers
The 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 agent that calls, so the user's replies to its posts are delivered too. A trigger you make for an agent is made for your own agent: naming another agent, by agentId or by agentName, is refused, and one agent has one trigger (a second create is refused with the triggerId to update). The transport never changes on update; delete and create again. Twenty per account. A trigger that belongs to another of the user's agents is theirs alone: you can list it, and only that agent or the user changes or deletes it. 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).
Path
id: For update and delete: the trigger's id (from list).
Returns 200
triggers(object[]): For list.events(object[]): For list: the catalogue.trigger(object): For create and update.secret(string | null): For create: the signing secret, this once; null for a poll trigger.deleted(boolean): For delete.
Example
curl -X DELETE "https://api.roma.app/api/v1/triggers/<id>" \
-H "Authorization: Bearer roma_…"
Experts
GET /experts
The user's experts, each with the opening line of its instructions · Read-only · MCP tool list_experts
List 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.
Returns 200
count(number)experts(object[])
Example
curl -X GET "https://api.roma.app/api/v1/experts" \
-H "Authorization: Bearer roma_…"
POST /experts
Create an expert · Adds data · MCP tool create_expert
Create 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.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | The expert's name, how the user will call it in (two or three words, the way a job title reads). (up to 120 characters) |
instructions | string | yes | The whole standing instructions, as Markdown. |
icon | "experts" | "writing" | "editing" | "review" | "ideas" | "creative" | "humor" | "language" | "book" | "business" | "goal" | "guidance" | "launch" | "winning" | "teaching" | "planning" | "productivity" | "pitch" | "marketing" | "people" | "support" | "like" | "email" | "voice" | "money" | "banking" | "accounting" | "investing" | "data" | "legal" | "pricing" | "shopping" | "code" | "databases" | "computing" | "science" | "research" | "vision" | "design" | "art" | "fixing" | "architecture" | "product" | "security" | "health" | "care" | "love" | "household" | "city" | "school" | "travel" | "maps" | "world" | "cars" | "music" | "photo" | "film" | "gaming" | "events" | "gift" | "crafts" | "sea" | "sunshine" | "night" | null | no | The icon it wears in Roma, from the set. Omit, or pass null, for the default. |
Returns 201
id(string)name(string)firstLine(string): The opening line of its instructions.icon(string | null): The icon it wears in Roma — a name of the expert icon set, or null for the default.updatedAt(string)webUrl(string): The expert's page in Roma on the web.
Example
curl -X POST "https://api.roma.app/api/v1/experts" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","instructions":"<instructions>"}'
GET /experts/{id}
One expert with its whole instructions · Read-only · MCP tool get_expert
Read 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.
Path
id: The expert's id. Pass this orname.
Returns 200
id(string)name(string)firstLine(string): The opening line of its instructions.icon(string | null): The icon it wears in Roma — a name of the expert icon set, or null for the default.updatedAt(string)webUrl(string): The expert's page in Roma on the web.instructions(string): The whole standing instructions, as Markdown.
Example
curl -X GET "https://api.roma.app/api/v1/experts/<id>" \
-H "Authorization: Bearer roma_…"
PATCH /experts/{id}
Rename an expert, pick its icon or replace its instructions · Updates or removes existing data · MCP tool update_expert
Update one of the user's experts: its name, its instructions, its icon, or any of them. 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, should be called something else, or should wear another icon.
Path
id: The expert's id (from list_experts, get_expert or get_context).
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | null | no | A new name. Omit, or pass null, to keep it. |
instructions | string | null | no | The whole standing instructions, as Markdown, replacing the body. Omit, or pass null, to keep it. |
icon | "experts" | "writing" | "editing" | "review" | "ideas" | "creative" | "humor" | "language" | "book" | "business" | "goal" | "guidance" | "launch" | "winning" | "teaching" | "planning" | "productivity" | "pitch" | "marketing" | "people" | "support" | "like" | "email" | "voice" | "money" | "banking" | "accounting" | "investing" | "data" | "legal" | "pricing" | "shopping" | "code" | "databases" | "computing" | "science" | "research" | "vision" | "design" | "art" | "fixing" | "architecture" | "product" | "security" | "health" | "care" | "love" | "household" | "city" | "school" | "travel" | "maps" | "world" | "cars" | "music" | "photo" | "film" | "gaming" | "events" | "gift" | "crafts" | "sea" | "sunshine" | "night" | null | no | A new icon from the set; experts is the default. Omit, or pass null, to keep it. |
baseUpdatedAt | string | null | no | The updatedAt get_expert returned; when the expert changed since, the write is refused and the body is read again. |
Returns 200
id(string)name(string)firstLine(string): The opening line of its instructions.icon(string | null): The icon it wears in Roma — a name of the expert icon set, or null for the default.updatedAt(string)webUrl(string): The expert's page in Roma on the web.changed(string[]): Which ofname,instructionsandiconchanged.
Example
curl -X PATCH "https://api.roma.app/api/v1/experts/<id>" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{}'
GET /experts/{id}/versions
The version history of an expert's instructions, newest first · Read-only · MCP tool list_versions
List 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. Versions are kept for the item's life; a long history pages by before.
Path
id: The item's or the expert's id (from list_items, search, get_item or list_experts).
Returns 200
id(string)hint(string)versions(object[])
Example
curl -X GET "https://api.roma.app/api/v1/experts/<id>/versions" \
-H "Authorization: Bearer roma_…"
POST /experts/{id}/versions/{versionId}/restore
Restore an expert's instructions to an earlier version · Updates or removes existing data · MCP tool restore_version
Restore 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.
Path
id: The item's or the expert's id.versionId: The version to restore, from list_versions.
Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
acceptLaterEdits | boolean | null | no | true only after the person said yes to losing the edits made in Roma after that version, the ones the needsConfirmation answer named. Omit on the first call. |
Returns 200
restored(boolean)id(string)title(string | null)needsConfirmation(boolean)laterEdits(object[])hint(string)
Example
curl -X POST "https://api.roma.app/api/v1/experts/<id>/versions/<versionId>/restore" \
-H "Authorization: Bearer roma_…" \
-H "Content-Type: application/json" \
-d '{}'
Memory
GET /memory/lookup
Roma's journal of what happened, for a span and words · Read-only · MCP tool lookup_memories
Read 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.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | no | First local day of the span, YYYY-MM-DD. Without it: 90 days back. |
to | string | no | Last local day of the span, YYYY-MM-DD, inclusive. Without it: yesterday. |
query | string | no | Two to five plain words a matching entry would contain — a person's name, a place, a thing. Any word matches. (up to 200 characters) |
kind | "day" | "week" | "month" | no | Only entries of this period. Leave out to get whatever fits. |
Returns 200
span(object)headlines(object[])entries(object[])note(string)
Example
curl -X GET "https://api.roma.app/api/v1/memory/lookup" \
-H "Authorization: Bearer roma_…"