Install Jentic One Beta
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Roma API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Froma.app%2Froma" | shStep 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Froma.app%2Froma" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
What an agent can do with Roma API.
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
GET STARTED
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
Patterns agents use Roma API for, with concrete tasks.
★ 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.
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.
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.
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.
Call POST /api/v1/artifacts/{id}/messages on the task with message 'Draft ready for review', agentName 'research-bot', and needsInput true
34 endpoints — 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.
METHOD
PATH
DESCRIPTION
/api/v1/context
The workspace in one call
/api/v1/tasks
Create a task
/api/v1/tasks/batch
Create up to 100 tasks
/api/v1/tasks
List and filter tasks
/api/v1/notes
Create a note
/api/v1/collections/{id}/items
Add rows to a collection
/api/v1/artifacts/{id}/messages
Post a message into a task's chat
/api/v1/automations/{id}/run
Start an automation now
/api/v1/context
The workspace in one call
/api/v1/tasks
Create a task
/api/v1/tasks/batch
Create up to 100 tasks
/api/v1/tasks
List and filter tasks
/api/v1/notes
Create a note
/api/v1/collections/{id}/items
Add rows to a collection
/api/v1/artifacts/{id}/messages
Post a message into a task's chat
/api/v1/automations/{id}/run
Start an automation now
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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.
Alternatives and complements available in the Jentic catalogue.
Specific to using Roma API through Jentic.
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.
For 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.
Use for: Get the user's workspace overview before we start, Create a high-priority task due Friday, I need to add these twelve action items as tasks in one go, List all tasks that are in progress
Not supported: Does not manage shared team workspaces, send email, or sync calendars. Use for one person's own Roma tasks, notes, collections, and automations only.
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.
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.
Base layer of spec validity and structural soundness.
Aggregated quality score from linter diagnostics, weighted by severity.
Percentage of `$ref` references that resolve successfully.
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
Structural correctness score based on schema issues using logarithmic dampening.
Clarity, completeness, and ingestion readiness for developers and tooling.
How richly the API is illustrated with examples.
Percentage of examples that conform to their schemas.
Percentage of operations with complete response definitions (success, client error, server error).
Health of API ingestion, bundling, and resolution within Jentic pipelines.
Semantic breadth, depth, and agent comprehension for AI systems.
Coverage of descriptions across API elements.
Coverage of RFC 9457 Problem Details for error responses.
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
Coverage of summaries across operations/tags/info.
Functional utility, complexity comfort, and AI orchestration readiness.
Agent comfort level based on API operational and structural complexity.
Trust, risk posture, and security compliance.
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
Findability, semantic richness, and reasoning readiness.
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>