{"openapi":"3.1.0","info":{"title":"Roma API","version":"1","description":"The user's own Roma workspace: tasks, notes, projects, typed lists (collections) and automations. A place an AI chat can store work, pick it up again and keep knowledge between conversations.\n\nEvery call acts as the signed-in person, on their own workspace. Authenticate with a Roma API key (Settings → Connections) or an OAuth access token as a bearer. The same operations are available over the Model Context Protocol at /mcp; this REST surface exists for tools that speak HTTP rather than MCP (Zapier, Make, n8n, a script).","contact":{"name":"Roma","url":"https://roma.app","email":"hello@roma.app"},"termsOfService":"https://roma.app/terms","x-logo":{"url":"https://roma.app/icon.svg"}},"externalDocs":{"description":"Developer docs","url":"https://roma.app/developers"},"servers":[{"url":"https://api.roma.app","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Context"},{"name":"Tasks"},{"name":"Projects"},{"name":"Notes and search"},{"name":"Collections"},{"name":"Trash"},{"name":"Automations"}],"paths":{"/api/v1/context":{"get":{"operationId":"getContext","summary":"The workspace in one call","description":"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 projects; overdue, due-today, in-progress and upcoming tasks; unsorted tasks; recently touched notes; their collections with columns; their automations with the last run; and the last few days of activity. Everything comes with ids for follow-up calls. It is an overview, not the full data: use search, list_tasks, get_note or get_collection_items for depth. Pass focusProjectId to scope the task sections to one project.","tags":["Context"],"x-roma-tool":"get_context","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"focusProjectId","in":"query","required":false,"description":"Optional project UUID. Scopes the task sections to that project; the rest stays workspace-wide.","schema":{"description":"Optional project UUID. Scopes the task sections to that project; the rest stays workspace-wide.","type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"about":{"type":"array","items":{"type":"string"}},"user":{"type":"object","properties":{"timezone":{"type":"string"},"today":{"type":"string"},"localTime":{"type":"string"}},"required":["timezone","today","localTime"],"additionalProperties":{}},"unavailable":{"type":"array","items":{"type":"string"}}},"required":["about","user","unavailable"],"additionalProperties":{}}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}}},"/api/v1/tasks":{"get":{"operationId":"listTasks","summary":"List and filter tasks","description":"List, filter, and search the user's tasks — the way to find work to pick up. Returns tasks ordered by due date, then priority. Scope to the whole workspace, unsorted tasks only, or a single project. By default completed tasks are excluded.","tags":["Tasks"],"x-roma-tool":"list_tasks","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"scope","in":"query","required":false,"description":"\"all\" (default) for everything, \"inbox\" for unsorted items only (no project — the value keeps its legacy name), or a project UUID for that project.","schema":{"description":"\"all\" (default) for everything, \"inbox\" for unsorted items only (no project — the value keeps its legacy name), or a project UUID for that project.","type":"string"}},{"name":"query","in":"query","required":false,"description":"Free-text search across title and description.","schema":{"description":"Free-text search across title and description.","type":"string"}},{"name":"taskStatus","in":"query","required":false,"description":"Filter to these statuses. Omit to use the default active set (excludes completed).","schema":{"description":"Filter to these statuses. Omit to use the default active set (excludes completed).","type":"array","items":{"type":"string","enum":["todo","inProgress","completed"]}},"style":"form","explode":false},{"name":"dueAfter","in":"query","required":false,"description":"ISO 8601 instant — only tasks due on/after this (inclusive).","schema":{"description":"ISO 8601 instant — only tasks due on/after this (inclusive).","type":"string"}},{"name":"dueBefore","in":"query","required":false,"description":"ISO 8601 instant — only tasks due before this (exclusive). Today = dueAfter today 00:00 local, dueBefore tomorrow 00:00 local; overdue = dueBefore today 00:00 alone.","schema":{"description":"ISO 8601 instant — only tasks due before this (exclusive). Today = dueAfter today 00:00 local, dueBefore tomorrow 00:00 local; overdue = dueBefore today 00:00 alone.","type":"string"}},{"name":"createdAfter","in":"query","required":false,"description":"ISO 8601 instant — only tasks created on/after this.","schema":{"description":"ISO 8601 instant — only tasks created on/after this.","type":"string"}},{"name":"createdBefore","in":"query","required":false,"description":"ISO 8601 instant — only tasks created before this (exclusive).","schema":{"description":"ISO 8601 instant — only tasks created before this (exclusive).","type":"string"}},{"name":"updatedAfter","in":"query","required":false,"description":"ISO 8601 instant — only tasks last changed on/after this.","schema":{"description":"ISO 8601 instant — only tasks last changed on/after this.","type":"string"}},{"name":"updatedBefore","in":"query","required":false,"description":"ISO 8601 instant — only tasks last changed before this (exclusive).","schema":{"description":"ISO 8601 instant — only tasks last changed before this (exclusive).","type":"string"}},{"name":"completedAfter","in":"query","required":false,"description":"ISO 8601 instant — only tasks completed on/after this. Implies completed tasks unless taskStatus says otherwise.","schema":{"description":"ISO 8601 instant — only tasks completed on/after this. Implies completed tasks unless taskStatus says otherwise.","type":"string"}},{"name":"completedBefore","in":"query","required":false,"description":"ISO 8601 instant — only tasks completed before this (exclusive).","schema":{"description":"ISO 8601 instant — only tasks completed before this (exclusive).","type":"string"}},{"name":"sort","in":"query","required":false,"description":"Row order. Default 'due' (due date, then priority); a timestamp sort returns newest first.","schema":{"description":"Row order. Default 'due' (due date, then priority); a timestamp sort returns newest first.","type":"string","enum":["due","created","updated","completed"]}},{"name":"limit","in":"query","required":false,"description":"Max results (default 50).","schema":{"description":"Max results (default 50).","type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"priority":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"editedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":{}}}},"required":["count","tasks"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}},"post":{"operationId":"createTask","summary":"Create a task","description":"Create a task. Omit projectId to leave it unsorted (no project); set projectId to file it under a project. The task is enriched by AI in the background after creation, so enriched fields may appear on a subsequent read. Returns the created task.","tags":["Tasks"],"x-roma-tool":"create_task","x-roma-read-only":false,"x-roma-destructive":false,"parameters":[],"responses":{"201":{"description":"Created; the body is the new item.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"priority":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"editedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":{}}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Short, clear task title."},"description":{"description":"Optional longer details.","type":"string"},"projectId":{"description":"Project UUID. Omit to leave it unsorted (no project).","type":"string"},"priority":{"type":"string","enum":["low","medium","high"]},"taskStatus":{"description":"Defaults to 'todo'.","type":"string","enum":["todo","inProgress","completed"]},"dueAt":{"description":"ISO 8601 due timestamp.","type":"string"}},"required":["title"],"additionalProperties":false}}}}}},"/api/v1/quick-add":{"post":{"operationId":"quickAdd","summary":"Create a task from one line of text","description":"Create a task. Omit projectId to leave it unsorted (no project); set projectId to file it under a project. The task is enriched by AI in the background after creation, so enriched fields may appear on a subsequent read. Returns the created task.","tags":["Tasks"],"x-roma-tool":"create_task","x-roma-read-only":false,"x-roma-destructive":false,"parameters":[],"responses":{"201":{"description":"Created; the body is the new item.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"priority":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"editedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":{}}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Short, clear task title."},"description":{"description":"Optional longer details.","type":"string"},"projectId":{"description":"Project UUID. Omit to leave it unsorted (no project).","type":"string"},"priority":{"type":"string","enum":["low","medium","high"]},"taskStatus":{"description":"Defaults to 'todo'.","type":"string","enum":["todo","inProgress","completed"]},"dueAt":{"description":"ISO 8601 due timestamp.","type":"string"}},"required":["text"],"additionalProperties":false}}}}}},"/api/v1/tasks/{id}":{"get":{"operationId":"getTask","summary":"One task with its subtasks and project","description":"Fetch one task with everything needed to start working on it: the full task row (description, status, priority, due date) and the project it belongs to. The equivalent of opening an issue.","tags":["Tasks"],"x-roma-tool":"get_task_context","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"id","in":"path","required":true,"description":"The task's UUID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"priority":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"editedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":{}},"project":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":{}},{"type":"null"}]}},"required":["task","project"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}},"patch":{"operationId":"updateTask","summary":"Update a task","description":"Update fields on an existing task — title, body, status, priority, due date, or which project it is in (projectId; null moves it out to unsorted). Use status transitions to report progress (e.g. todo → inProgress → completed). Only the fields you pass are changed. The body merge mode controls how `description` combines with the existing body — adding text appends/prepends; it never replaces unless you explicitly ask it to.","tags":["Tasks"],"x-roma-tool":"update_task","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"description":"The task's UUID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"priority":{"anyOf":[{"type":"string"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"editedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":{}}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"description":"Body text to merge in per `mode`. Omit to leave the body unchanged; null to clear it.","anyOf":[{"type":"string"},{"type":"null"}]},"mode":{"description":"How `description` 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; never to add content; requires confirmReplace: true).","type":"string","enum":["prepend","append","replace","insertAfter"]},"confirmReplace":{"description":"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.","type":"boolean"},"anchor":{"description":"For mode 'insertAfter' only: a verbatim snippet of the existing line to insert after. Errors if not found.","type":"string"},"taskStatus":{"type":"string","enum":["todo","inProgress","completed"]},"priority":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}]},"dueAt":{"description":"ISO 8601 timestamp, or null to clear.","anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"description":"Move the task: a project UUID (from list_projects or get_context) files it there; null moves it out to unsorted. Omit to leave it where it is.","anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}}},"delete":{"operationId":"deleteTask","summary":"Delete a task into the trash","description":"Delete a task (or subtask) by id. This is a SOFT delete — the task is recoverable for ~30 days before it is purged. Deleting a task also removes it from search. Deletes one task per call so each delete is confirmed individually.","tags":["Tasks"],"x-roma-tool":"delete_task","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"description":"The task's UUID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["deleted","id"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}}},"/api/v1/projects":{"get":{"operationId":"listProjects","summary":"List projects","description":"List all of the user's projects. Use this to resolve a project name to its UUID before creating or filing a task, or to understand the workspace structure.","tags":["Projects"],"x-roma-tool":"list_projects","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":{}}}},"required":["count","projects"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}},"post":{"operationId":"createProject","summary":"Create a project","description":"Create a project — a folder that groups the user's tasks and notes. Use it when the user wants a new project, or to give work a home that has none; check list_projects or get_context first so an existing project is not duplicated. Returns the project with its id, ready for create_task / update_task projectId.","tags":["Projects"],"x-roma-tool":"create_project","x-roma-read-only":false,"x-roma-destructive":false,"parameters":[],"responses":{"201":{"description":"Created; the body is the new item.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":{}}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Project name, in the user's own words."},"emoji":{"description":"Optional single emoji for the project.","type":"string"}},"required":["name"],"additionalProperties":false}}}}}},"/api/v1/projects/{id}":{"patch":{"operationId":"updateProject","summary":"Rename a project or set its emoji","description":"Rename a project or change its emoji. Only the fields you pass change; emoji null removes it. Does not move or change the project's tasks.","tags":["Projects"],"x-roma-tool":"update_project","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"description":"The project's UUID (from list_projects or get_context).","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":{}}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name.","type":"string","minLength":1},"emoji":{"description":"New emoji, or null to remove it.","anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}}}},"/api/v1/search":{"get":{"operationId":"search","summary":"Search notes, tasks and list rows","description":"Search the user's Roma workspace — their notes, tasks, typed lists and the rows inside them — 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; get_note returns a note's full text. An empty result means nothing relevant is saved. Not for general web knowledge.","tags":["Notes and search"],"x-roma-tool":"search","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"q","in":"query","required":true,"description":"Natural-language query — what the user is trying to find, in their words.","schema":{"type":"string","description":"Natural-language query — what the user is trying to find, in their words."}},{"name":"limit","in":"query","required":false,"description":"Max results (default 10).","schema":{"description":"Max results (default 10).","type":"integer","minimum":1,"maximum":20}},{"name":"after","in":"query","required":false,"description":"Only items CREATED on/after this ISO 8601 timestamp. Use when scoping by when it was saved (\"last week\", \"in March\").","schema":{"description":"Only items CREATED on/after this ISO 8601 timestamp. Use when scoping by when it was saved (\"last week\", \"in March\").","type":"string"}},{"name":"before","in":"query","required":false,"description":"Only items CREATED before this ISO 8601 timestamp (exclusive). Pair with `after` to bound a window.","schema":{"description":"Only items CREATED before this ISO 8601 timestamp (exclusive). Pair with `after` to bound a window.","type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["task","note","doc","collectionItem","collection"]},"id":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string"},"collectionId":{"type":"string"},"collectionName":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","id","title","snippet"],"additionalProperties":{}}}},"required":["count","results"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}}},"/api/v1/notes":{"get":{"operationId":"listNotes","summary":"List notes","description":"List the user's notes, newest first. Scope to the whole workspace, unsorted notes only, or a single project. Returns a snippet of each body; use get_note for the full text. This is browse-by-container — use search to find by topic.","tags":["Notes and search"],"x-roma-tool":"list_notes","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"scope","in":"query","required":false,"description":"\"all\" (default) for everything, \"inbox\" for unsorted items only (no project — the value keeps its legacy name), or a project UUID for that project.","schema":{"description":"\"all\" (default) for everything, \"inbox\" for unsorted items only (no project — the value keeps its legacy name), or a project UUID for that project.","type":"string"}},{"name":"createdAfter","in":"query","required":false,"description":"ISO 8601 instant — only notes created on/after this.","schema":{"description":"ISO 8601 instant — only notes created on/after this.","type":"string"}},{"name":"createdBefore","in":"query","required":false,"description":"ISO 8601 instant — only notes created before this (exclusive).","schema":{"description":"ISO 8601 instant — only notes created before this (exclusive).","type":"string"}},{"name":"updatedAfter","in":"query","required":false,"description":"ISO 8601 instant — only notes last changed on/after this.","schema":{"description":"ISO 8601 instant — only notes last changed on/after this.","type":"string"}},{"name":"updatedBefore","in":"query","required":false,"description":"ISO 8601 instant — only notes last changed before this (exclusive).","schema":{"description":"ISO 8601 instant — only notes last changed before this (exclusive).","type":"string"}},{"name":"sort","in":"query","required":false,"description":"Row order, newest first on that stamp. Default created.","schema":{"description":"Row order, newest first on that stamp. Default created.","type":"string","enum":["created","updated"]}},{"name":"limit","in":"query","required":false,"description":"Max results (default 50).","schema":{"description":"Max results (default 50).","type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"docs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"snippet":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","snippet"],"additionalProperties":{}}}},"required":["count","docs"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}},"post":{"operationId":"createNote","summary":"Create a note","description":"Capture a note for the user. Omit projectId to leave it unsorted (no project); set projectId to file it under a project. The body is stored as authored within the editor's supported Markdown subset (unsupported constructs degrade to plain text) — no AI cleanup or reclassification runs — and indexed for search. Returns the created note.","tags":["Notes and search"],"x-roma-tool":"create_note","x-roma-read-only":false,"x-roma-destructive":false,"parameters":[],"responses":{"201":{"description":"Created; the body is the new item.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"content":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","content"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"The note body, as Markdown (headings `#`, lists, task lists `- [ ]`, bold, links — the editor's supported subset). Rendered to rich text; author real Markdown, not literal markers."},"title":{"description":"Short title. Omit to let the body speak for itself.","type":"string"},"projectId":{"description":"Project UUID. Omit to leave it unsorted (no project).","type":"string"}},"required":["content"],"additionalProperties":false}}}}}},"/api/v1/notes/{id}":{"get":{"operationId":"getNote","summary":"One note as Markdown","description":"Read one note in full by its id — the companion to search: search returns the matched passage, this pulls the whole document when you need more than the snippet. Returns the note's title and full body as Markdown, and, for a note a meeting was recorded into, the attributed transcript once its recording is done.","tags":["Notes and search"],"x-roma-tool":"get_note","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"id","in":"path","required":true,"description":"The note's UUID (from a search result).","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"transcript":{"type":"string"},"recording":{"type":"object","properties":{"durationMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"speakers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"],"additionalProperties":false}}},"required":["durationMs","speakers"],"additionalProperties":false}},"required":["id","title","content"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}},"patch":{"operationId":"updateNote","summary":"Update a note","description":"Edit an existing note — its title, body, or which project it's in. Only the fields you pass change. The body merge mode controls how `content` combines with the existing body. Re-indexes for search automatically.","tags":["Notes and search"],"x-roma-tool":"update_note","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"description":"The note's UUID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"content":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","content"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"New title. Omit to leave unchanged.","type":"string"},"content":{"description":"Markdown body to merge in (headings, lists, bold, links). Omit for a title/project-only edit.","type":"string"},"mode":{"description":"How `content` merges: 'append' (default, at the bottom), 'prepend' (at the top), 'replace' (swap the whole body — only when the user explicitly asked to rewrite it; never to add content; requires confirmReplace: true), or 'insertAfter' (place it right after the line named in `anchor`, matching that line's formatting).","type":"string","enum":["prepend","append","replace","insertAfter"]},"confirmReplace":{"description":"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.","type":"boolean"},"anchor":{"description":"For mode 'insertAfter' only: a verbatim snippet of the existing line to insert after. Errors if not found.","type":"string"},"projectId":{"description":"Project UUID to move the note into, or \"inbox\" to clear its project (unsorted — the value keeps its legacy name). Omit to leave it where it is.","type":"string"}},"additionalProperties":false}}}}},"delete":{"operationId":"deleteNote","summary":"Delete a note into the trash","description":"Delete a note by id. This is a SOFT delete — the note is recoverable for ~30 days before it is purged. Deleting a note also removes it from search. Deletes one note per call so each delete is confirmed individually.","tags":["Notes and search"],"x-roma-tool":"delete_note","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"description":"The note's UUID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["deleted","id"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}}},"/api/v1/collections":{"get":{"operationId":"listCollections","summary":"List collections with their columns","description":"List the user's collections (typed lists — a reading list, a watchlist, an expenses tracker). Returns each list's id, name, standing instructions, row count, and its COLUMNS with their stable ids — the ids add_collection_items and update_collection_items take. Use it before writing to a collection whose columns you have not read yet. Pass suppressOptions: true when you only need names/counts — select columns can carry hundreds of options (you don't need them to write: a select value may be sent as its label).","tags":["Collections"],"x-roma-tool":"list_collections","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"suppressOptions","in":"query","required":false,"description":"true replaces each select column's option list with an optionCount — much smaller payload.","schema":{"description":"true replaces each select column's option list with an optionCount — much smaller payload.","type":"boolean"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}]},"itemCount":{"type":"number"},"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"optionCount":{"type":"number"}},"required":["id","name","type"],"additionalProperties":false}}},"required":["id","name","instructions","itemCount","columns"],"additionalProperties":false}}},"required":["count","collections"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}},"post":{"operationId":"createCollection","summary":"Create a collection","description":"Create a typed list with its columns. Every column is equal — declare the ones the list actually needs, including a name column if rows have names (a list of measurements or dates may have none). Returns the created list WITH the stable column ids to use when adding rows.","tags":["Collections"],"x-roma-tool":"create_collection","x-roma-read-only":false,"x-roma-destructive":false,"parameters":[],"responses":{"201":{"description":"Created; the body is the new item.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"optionCount":{"type":"number"}},"required":["id","name","type"],"additionalProperties":false}}},"required":["id","name","columns"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The list's name."},"instructions":{"description":"Standing rules for how entries should be handled, one rule per line. Max 500 characters — they ride in the prompt on every turn.","type":"string","maxLength":500},"properties":{"description":"The columns. Omit to start with one default text column the user can rename, retype or delete.","type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"type":{"type":"string","enum":["text","number","date","url","select","multiSelect"]},"options":{"description":"select/multiSelect columns only: the choice labels.","type":"array","items":{"type":"string","minLength":1}}},"required":["name","type"]}}},"required":["name"],"additionalProperties":false}}}}}},"/api/v1/collections/{id}":{"patch":{"operationId":"updateCollection","summary":"Rename a collection or replace its instructions","description":"Rename a collection or edit its standing instructions. `instructions` REPLACES the existing text — read the current value first (list_collections) and carry forward anything still true; null clears them. Column (schema) editing is not available over MCP — new select options mint automatically when adding or updating rows.","tags":["Collections"],"x-roma-tool":"update_collection","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"description":"The collection's UUID (from list_collections).","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","instructions"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New list name.","type":"string","minLength":1},"instructions":{"description":"REPLACES the standing rules (max 500 characters — they ride the prompt every turn); null clears them.","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"additionalProperties":false}}}}},"delete":{"operationId":"deleteCollection","summary":"Delete a collection into the trash","description":"Delete a collection (typed list) by id. Deleting the list also deletes ALL its rows. SOFT delete — the list and its rows are recoverable for ~30 days via restore_deleted (type \"collection\"), which brings the rows deleted with it back too. When the list still holds rows the call refuses unless confirmDeleteItems is true, so the blast radius is always named before it happens.","tags":["Collections"],"x-roma-tool":"delete_collection","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"description":"The collection's UUID (from list_collections).","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"},"name":{"type":"string"},"itemsDeleted":{"type":"number"}},"required":["deleted","id","name","itemsDeleted"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmDeleteItems":{"description":"Required (true) when the list holds rows: confirms deleting the list AND every row in it. Confirm with the user first.","type":"boolean"}},"additionalProperties":false}}}}}},"/api/v1/collections/{id}/items":{"get":{"operationId":"listCollectionItems","summary":"Rows of a collection, paged","description":"Read the rows of one collection. Values are keyed by COLUMN ID (see list_collections); a select column's value is an option id, a multiSelect column's an array of option ids. Each row also lists its image attachments (so you can verify an import's images actually landed); pass includeImageUrls: true for short-lived viewable links. Paginated: the result carries totalCount and hasMore — keep calling with offset until hasMore is false to read a large list completely. Archived rows are left out unless includeArchived: true. Use to check what a list already holds before adding to it.","tags":["Collections"],"x-roma-tool":"get_collection_items","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"id","in":"path","required":true,"description":"The collection's UUID (from list_collections).","schema":{"type":"string"}},{"name":"includeArchived","in":"query","required":false,"description":"true also returns archived rows (hidden from every list by default) so one can be brought back with update_collection_items; each row then says whether it is archived.","schema":{"description":"true also returns archived rows (hidden from every list by default) so one can be brought back with update_collection_items; each row then says whether it is archived.","type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Max rows per page (default 50, newest first).","schema":{"description":"Max rows per page (default 50, newest first).","type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","required":false,"description":"Rows to skip — page through a big list with offset + limit until hasMore is false.","schema":{"description":"Rows to skip — page through a big list with offset + limit until hasMore is false.","type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"includeImageUrls","in":"query","required":false,"description":"true additionally returns a short-lived signed `url` per attachment so the images can be viewed. Off by default.","schema":{"description":"true additionally returns a short-lived signed `url` per attachment so the images can be viewed. Off by default.","type":"boolean"}},{"name":"createdAfter","in":"query","required":false,"description":"ISO 8601 instant — only rows added on/after this.","schema":{"description":"ISO 8601 instant — only rows added on/after this.","type":"string"}},{"name":"createdBefore","in":"query","required":false,"description":"ISO 8601 instant — only rows added before this (exclusive).","schema":{"description":"ISO 8601 instant — only rows added before this (exclusive).","type":"string"}},{"name":"updatedAfter","in":"query","required":false,"description":"ISO 8601 instant — only rows last changed on/after this.","schema":{"description":"ISO 8601 instant — only rows last changed on/after this.","type":"string"}},{"name":"updatedBefore","in":"query","required":false,"description":"ISO 8601 instant — only rows last changed before this (exclusive).","schema":{"description":"ISO 8601 instant — only rows last changed before this (exclusive).","type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"totalCount":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"body":{"anyOf":[{"type":"string"},{"type":"null"}]},"archivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"attachments":{"type":"array","items":{"type":"object","properties":{"bucketPath":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"number"},"url":{"type":"string"}},"required":["bucketPath","mimeType","sizeBytes"],"additionalProperties":{}}}},"required":["id","values","archivedAt","attachments"],"additionalProperties":false}}},"required":["count","totalCount","offset","hasMore","items"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}},"post":{"operationId":"addCollectionItems","summary":"Add rows to a collection","description":"Add rows to a collection, many in one call (the import path). Values are keyed by column id or name; a select value may be its label or option id, a multiSelect value is an ARRAY of them, and unknown labels become new options. Keys that match no column come back in `unknownKeys`. Images that could not be stored come back in `imageFailures` with the reason; create_image_upload is the reliable path for images. Every row is inserted unless `matchOn` names columns to match on; a matched row keeps every filled cell and only gains what it lacks (empty cells, notes, images), so nothing is overwritten. To change a filled cell use update_collection_items (re-adding without matchOn creates a duplicate).","tags":["Collections"],"x-roma-tool":"add_collection_items","x-roma-read-only":false,"x-roma-destructive":false,"parameters":[{"name":"id","in":"path","required":true,"description":"The collection's UUID (from list_collections).","schema":{"type":"string"}}],"responses":{"201":{"description":"Created; the body is the new item.","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"number"},"itemIds":{"type":"array","items":{"type":"string"}},"unknownKeys":{"type":"array","items":{"type":"string"}},"imagesAttached":{"type":"number"},"imageFailures":{"type":"array","items":{"type":"object","properties":{"item":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"reason":{"type":"string"}},"required":["item","source","reason"],"additionalProperties":false}}},"required":["added","itemIds","unknownKeys","imagesAttached","imageFailures"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"matchOn":{"description":"Column ids or names that identify an existing row. When given, a row whose listed cells all match an existing row is not added again: the existing row gains the incoming row's empty-cell values, notes and images and keeps every cell it already had; matching is exact. Omit to always insert — no column is a natural key, so there is no default dedup.","type":"array","items":{"type":"string"}},"items":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"values":{"description":"Column values keyed by column id or column name.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"body":{"description":"Freeform notes for the row.","anyOf":[{"type":"string"},{"type":"null"}]},"imageUrls":{"description":"Images for this row: a Roma storage path (from create_image_upload) or a public https image URL the server downloads (images only, ≤10 MB). Max 5 per row, 30 per call.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string"}},{"type":"null"}]}}},"description":"Every row to add, in one call."}},"required":["items"],"additionalProperties":false}}}}},"patch":{"operationId":"updateCollectionItems","summary":"Correct rows of a collection","description":"Update existing rows of ONE collection, many in one call; pass only what changes. `values` MERGE into the row (only the keys sent change; \"\" clears a cell), `body` replaces the notes, `imageUrls` add images (clearImages: true drops the old ones first), `archived` sets a row aside or brings it back. A key matching no column is an error; rows earlier in the batch stay updated and are named, so re-send only the rest. Read row ids and current values with get_collection_items first.","tags":["Collections"],"x-roma-tool":"update_collection_items","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"description":"The collection's UUID (from list_collections).","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"number"},"itemIds":{"type":"array","items":{"type":"string"}},"imagesAttached":{"type":"number"},"imageFailures":{"type":"array","items":{"type":"object","properties":{"item":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"reason":{"type":"string"}},"required":["item","source","reason"],"additionalProperties":false}}},"required":["updated","itemIds","imagesAttached","imageFailures"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","description":"The row's UUID (from get_collection_items)."},"values":{"description":"Column values to set, keyed by column id or column name — MERGED into the row's existing values. An empty string \"\" clears that cell.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"body":{"description":"New freeform notes — REPLACES the row's notes; null clears them.","anyOf":[{"type":"string"},{"type":"null"}]},"imageUrls":{"description":"Images to add (same sources as add_collection_items). Max 5 per row, 30 per call.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string"}},{"type":"null"}]},"clearImages":{"description":"true removes the row's existing images first; any imageUrls then attach fresh.","type":"boolean"},"archived":{"description":"true archives the row — hidden from every list, kept and reversible; false brings it back; omit to leave it as it is.","type":"boolean"}},"required":["itemId"]},"description":"Every row to update, in one call."}},"required":["items"],"additionalProperties":false}}}}},"delete":{"operationId":"deleteCollectionItems","summary":"Delete rows into the trash","description":"Delete rows from collections by id — up to 50 per call. SOFT delete: every row stays recoverable for ~30 days via restore_deleted (type \"collectionItem\") before it is purged, and drops out of search. Returns a per-id result — ids that don't resolve are reported and the rest still delete.","tags":["Collections"],"x-roma-tool":"delete_collection_items","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"type":"string"}},"required":["id","deleted"],"additionalProperties":false}}},"required":["deleted","results"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string"},"description":"The rows' UUIDs (from get_collection_items). Up to 50 per call."}},"required":["itemIds"],"additionalProperties":false}}}}}},"/api/v1/uploads":{"post":{"operationId":"createImageUpload","summary":"Pre-signed slots for image bytes","description":"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 add_collection_items / update_collection_items. Keep images at or under 10 MB (maxBytes). Up to 10 slots per call.","tags":["Collections"],"x-roma-tool":"create_image_upload","x-roma-read-only":false,"x-roma-destructive":false,"parameters":[],"responses":{"201":{"description":"Created; the body is the new item.","content":{"application/json":{"schema":{"type":"object","properties":{"uploads":{"type":"array","items":{"type":"object","properties":{"uploadUrl":{"type":"string"},"bucketPath":{"type":"string"}},"required":["uploadUrl","bucketPath"],"additionalProperties":false}},"maxBytes":{"type":"number"},"validForSeconds":{"type":"number"}},"required":["uploads","maxBytes","validForSeconds"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mimeType":{"type":"string","enum":["image/png","image/jpeg","image/heic","image/webp"],"description":"The image type you will upload (all slots in one call share it)."},"count":{"description":"How many upload slots (default 1).","type":"integer","minimum":1,"maximum":10}},"required":["mimeType"],"additionalProperties":false}}}}}},"/api/v1/trash":{"get":{"operationId":"listTrash","summary":"What is in the trash","description":"The trash: everything soft-deleted in the last ~30 days — tasks, notes, collections, and collection rows — 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 all kinds.","tags":["Trash"],"x-roma-tool":"list_deleted","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"type","in":"query","required":false,"description":"Only this kind. Omit for all kinds.","schema":{"description":"Only this kind. Omit for all kinds.","type":"string","enum":["task","note","collection","collectionItem"]}},{"name":"limit","in":"query","required":false,"description":"Max entries per kind (default 25).","schema":{"description":"Max entries per kind (default 25).","type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["task","note","collection","collectionItem"]},"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"deletedAt":{"type":"string"},"purgesAt":{"type":"string"},"collectionId":{"type":"string"}},"required":["type","id","title","deletedAt","purgesAt"],"additionalProperties":{}}}},"required":["count","items"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}}},"/api/v1/trash/restore":{"post":{"operationId":"restoreDeleted","summary":"Restore one item from the trash","description":"Bring back one soft-deleted item from the trash (see list_deleted) — a task, note, collection, or collection row. Restoring a collection also brings back the rows deleted with it; a row whose list is still deleted can't come back alone (restore the collection instead). A restored task whose project was deleted meanwhile lands in the inbox (movedToInbox: true). Restores one item per call. If the item is already live the call succeeds with alreadyLive: true.","tags":["Trash"],"x-roma-tool":"restore_deleted","x-roma-read-only":false,"x-roma-destructive":false,"parameters":[],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"restored":{"type":"boolean"},"alreadyLive":{"type":"boolean"},"type":{"type":"string"},"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"restoredItems":{"type":"number"},"movedToInbox":{"type":"boolean"}},"required":["restored","type","id","title"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["task","note","collection","collectionItem"],"description":"The entry's type, as list_deleted reported it."},"id":{"type":"string","description":"The deleted item's UUID."}},"required":["type","id"],"additionalProperties":false}}}}}},"/api/v1/automations":{"get":{"operationId":"listAutomations","summary":"List automations","description":"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.","tags":["Automations"],"x-roma-tool":"list_automations","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"automations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"when":{"type":"string"},"nextRunAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","status","when","nextRunAt"],"additionalProperties":{}}}},"required":["count","automations"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}}},"/api/v1/automations/{id}/runs":{"get":{"operationId":"listAutomationRuns","summary":"Recent runs of an automation","description":"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.","tags":["Automations"],"x-roma-tool":"get_automation_runs","x-roma-read-only":true,"x-roma-destructive":false,"parameters":[{"name":"id","in":"path","required":true,"description":"The automation's id (from list_automations or get_context).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many runs, newest first (default 5, max 20).","schema":{"description":"How many runs, newest first (default 5, max 20).","type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":{}},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"string"},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","startedAt","finishedAt"],"additionalProperties":{}}}},"required":["automation","runs"],"additionalProperties":false}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}}},"/api/v1/automations/{id}/run":{"post":{"operationId":"runAutomation","summary":"Start an automation now","description":"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.","tags":["Automations"],"x-roma-tool":"run_automation","x-roma-read-only":false,"x-roma-destructive":true,"parameters":[{"name":"id","in":"path","required":true,"description":"The automation's id (from list_automations or get_context).","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"runId":{"type":"string"},"status":{"type":"string"}},"required":["id","name","runId","status"],"additionalProperties":{}}}}},"400":{"description":"The request was understood and refused; the error says what to change.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"401":{"description":"No usable bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"404":{"description":"No such item for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"405":{"description":"The path exists but not with this method; Allow lists the ones that work.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}},"429":{"description":"Over the rate limit; wait for Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A Roma API key (roma_…) from Settings → Connections, or an OAuth 2.1 access token obtained through the MCP server's authorization flow."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"One sentence saying what to change."},"code":{"type":"string","description":"invalid, notFound, methodNotAllowed, unauthorized, rateLimited or toolError."}},"required":["error"]}}}}