canonical: https://jentic.com/apis/roma.app/roma

# Roma App Roma API

The Roma API reads and writes a person's own Roma workspace of tasks, notes, projects, typed lists called collections, and automations, so an AI chat can store work and pick it up in a later conversation. A single context call returns the user's timezone, projects, overdue and due-today tasks, recent notes, and collections. Tasks can be created one at a time, from one line of text, or up to 100 in a batch, and collections take up to 200 rows per call. Deleted items go to a trash that can be restored, and automations can be started on demand.

## For AI agents

Load a Roma workspace in one call, then create and update tasks, notes, and collection rows, post progress into a task's chat, and run the user's automations.

## Scope

Does not manage shared team workspaces, send email, or sync calendars. Use for one person's own Roma tasks, notes, collections, and automations only.

## Capabilities

- Load the whole workspace with GET `/api/v1/context`, including overdue, due-today, and in-progress tasks
- Create tasks with title, priority, taskStatus, and dueAt, or up to 100 at once with the batch call
- Filter tasks by taskStatus, due, created, updated, and completed date ranges and sort order
- Capture Markdown notes and file them under a projectId
- Define typed collections with columns and add up to 200 rows per call, matching on existing rows
- Post a progress note or a needsInput question into a task's or note's chat as the agent
- Restore a deleted task, note, collection, or row from the trash

## Use cases

### Persistent memory for an AI assistant

An assistant that forgets everything between chats cannot follow up on work. Through Jentic the agent calls Roma's getContext at the start of a conversation to load the user's projects, due tasks, recent notes, and what they asked it to remember, then writes new tasks and notes back with createTask and createNote, using a bearer key held by the developer's own instance. The next conversation starts from the same workspace.

Example prompt: Call GET `/api/v1/context`, then call POST `/api/v1/tasks` with title 'Send revised proposal', priority 'high', taskStatus 'todo', and dueAt '2026-11-20T17:00:00Z'

### Turning meeting notes into tasks

After a meeting, a list of action items needs to land as real tasks. POST `/api/v1/tasks/batch` takes up to 100 rows with the same fields as a single task, and a call-level projectId files every row under one project. Each task is enriched by AI in the background, so a follow-up read with GET `/api/v1/tasks/{id}` shows the added fields.

Example prompt: Call POST `/api/v1/tasks/batch` with projectId for 'Website relaunch' and a tasks array of the eight action items, each with a title and dueAt

### Structured tracking in collections

Some work fits a table better than a task list, such as a hiring pipeline or a reading list. POST `/api/v1/collections` creates a typed list with its columns, POST `/api/v1/collections/{id}/items` adds up to 200 rows per call keyed by column id or name, and PATCH `/api/v1/collections/{id}/items` corrects existing rows.

Example prompt: Call POST `/api/v1/collections` with name 'Reading list', then call POST `/api/v1/collections/{id}/items` with items for three books keyed by the returned column ids

### Agent progress reporting

A long-running agent should report back where the user will see it. POST `/api/v1/artifacts/{id}/messages` posts a message into a task's or note's chat as the calling agent, with agentName and needsInput to flag a question, and the user sees it as an unread reply on every device. GET `/api/v1/artifacts/{id}/messages` reads the latest replies.

Example prompt: Call POST `/api/v1/artifacts/{id}/messages` on the task with message 'Draft ready for review', agentName 'research-bot', and needsInput true

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/context` | The workspace in one call |
| POST | `/api/v1/tasks` | Create a task |
| POST | `/api/v1/tasks/batch` | Create up to 100 tasks |
| GET | `/api/v1/tasks` | List and filter tasks |
| POST | `/api/v1/notes` | Create a note |
| POST | `/api/v1/collections/{id}/items` | Add rows to a collection |
| POST | `/api/v1/artifacts/{id}/messages` | Post a message into a task's chat |
| POST | `/api/v1/automations/{id}/run` | Start an automation now |

## Key resources

- **Context** — One-call workspace overview with user details, projects, due tasks, recent notes, and collections
- **Tasks** — Tasks with title, description, projectId, priority, taskStatus, dueAt, and subtasks
- **Notes** — Markdown notes filed under projects
- **Collections** — Typed lists with declared columns and paged rows
- **Automations** — User-defined automations that can be listed, run now, and inspected by run history
- **Trash** — Soft-deleted tasks, notes, collections, and rows that can be restored

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 69 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 51 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 89 / 100
- **View full report:** https://jentic.com/apis/roma.app/roma/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Roma by hand means minting a roma_ API key or running an OAuth 2.1 flow, sending it as a bearer, and learning which of its 34 operations to call first. Through Jentic you install once, import Roma from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Roma puts task, note, collection, and automation ids in the URL path (`/api/v1/tasks/{id}`, `/api/v1/automations/{id}/run`), so a rule can bound your agent to the operations a job needs and, where it matters, to one automation. You choose the operations it may call, so destructive ones like DELETE `/api/v1/collections/{id}` or deleteCollectionItems are not included unless you add them.
- **Credential handling:** Your Roma key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a task' or 'load my workspace', and Jentic returns the matching Roma operation, such as createTask or getContext, with its input schema.

## Related APIs

- **Asana** — Team task and project management with workspaces and assignees
- **Notion** — Pages and databases in a Notion workspace

## FAQ

### What authentication does the Roma API use?

The Roma OpenAPI spec declares HTTP bearer authentication. The bearer value is either a Roma API key starting with roma_ from Settings, Connections, or an OAuth 2.1 access token, and every call acts as that signed-in person on their own workspace. Through Jentic the key is stored by your own instance and sent as the bearer at call time.

### How many tasks can I create in one Roma API call?

POST `/api/v1/tasks/batch` accepts up to 100 tasks in its tasks array, each with the same fields as a single task, and an optional call-level projectId. For collections, POST `/api/v1/collections/{id}/items` adds up to 200 rows per call.

### What are the rate limits for the Roma API?

The OpenAPI spec does not specify rate limits. See the Roma site at https://roma.app/ for current limits.

### Is there a Roma MCP server?

Yes - the Roma spec says the same operations are offered over the Model Context Protocol at /mcp. You can also connect Roma directly through Jentic: your agent gets the full 34-endpoint surface without loading another server's tool definitions into its context, your credential is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### How do I add a task to Roma through Jentic?

Search Jentic for 'create a task in Roma', load the createTask operation (POST `/api/v1/tasks`), and send a title plus optional priority, taskStatus, dueAt, and projectId. For a line of free text, quickAdd at POST `/api/v1/quick-add` takes it as text instead. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Roma API?

Yes. For a capture-only assistant, write a rule that allows GET `/api/v1/context`, POST `/api/v1/tasks`, and POST `/api/v1/notes.` The agent can read the workspace and add tasks and notes, but it cannot delete anything, edit collections, or start automations, and every call it makes is logged.
