canonical: https://jentic.com/apis/commareports.com/commareports

# Commareports Comma API

The Comma API publishes HTML reports and edits them in place while keeping a full revision history. It lists and fetches individual revisions, produces a line-level diff between any two, and lets collaborators leave anchored comment threads that can be resolved or reopened. Reports can be published or unpublished with a password-protected share link, have assets attached, and be checked by reviewer agents against the head revision. Routines, skills, and connectors schedule regeneration so a report stays current without manual edits.

## For AI agents

Publish and revise HTML reports with full revision history: fetch and diff revisions, leave and resolve anchored comments, manage password-protected share links, attach assets, run reviewer agents, and schedule regeneration.

## Scope

Does not handle spreadsheets, BI dashboards, or email campaigns. Use for publishing, revising, reviewing, and sharing HTML reports only.

## Capabilities

- Publish an HTML report and update it in place
- Track a full revision history and diff two revisions line by line
- Leave anchored comment threads on a report and resolve or reopen them
- Publish, unpublish, and password-protect a report's share link
- Attach and remove assets on a report
- Run reviewer agents against a report's head revision
- Schedule regeneration with routines, skills, and connectors

## Use cases

### Agent Report Publishing

An AI agent connected through Jentic publishes a generated report and keeps it current: it creates the report from HTML, updates it in place as inputs change, and relies on Comma's revision history to diff what changed between versions. Because every edit is a revision, the agent can always show a line-level diff rather than overwriting silently.

Example prompt: Create a report from HTML, update it in place with new content, then return the line-level diff between the two revisions

### Review and Comment Loop

A team reviews a published report by leaving anchored comment threads, resolving them as they are addressed, and running reviewer agents against the head revision for an automated pass. The Comma API exposes the comment threads, replies, and reviewer runs, so an agent can gather open feedback and trigger a fresh review in one flow.

Example prompt: List a report's open comment threads, run the reviewer agents against the head revision, and report what each surfaced

### Scheduled Regeneration

A report that must stay current is wired to a routine that regenerates it on a schedule, drawing on skills and connectors for its data. Comma's routines, skills, and connectors operations let an agent set up the schedule, test a connector's credentials, and run the routine immediately to verify output before leaving it on a cadence.

Example prompt: Create a routine for a report, test its connector, and run the routine once to confirm the regenerated output

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/reports` | Create a report |
| GET | `/reports/{id}` | Fetch a report |
| PATCH | `/reports/{id}` | Update a report in place |
| GET | `/reports/{id}/revisions` | List a report's revisions |
| GET | `/reports/{id}/diff` | Diff two revisions line by line |
| GET | `/reports/search` | Full-text search reports |
| POST | `/reports/{id}/comments` | Leave a comment |
| POST | `/reports/{id}/review` | Run reviewer agents against the head revision |

## Key resources

- **Reports** — Create, fetch, update, and full-text search HTML reports
- **Revisions** — List revisions, fetch one, and diff two line by line
- **Comments** — Leave anchored threads, reply, and resolve or reopen
- **Sharing** — Publish or unpublish a share link and set or clear its password
- **Reviews** — Run reviewer agents and start Claude Code review sessions
- **Routines** — Schedule regeneration with routines, skills, and connectors

## 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:** 70 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 78 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 53 / 100
  - Agent Usability: 93 / 100
  - Security: 68 / 100
  - AI Discoverability: 78 / 100
- **View full report:** https://jentic.com/apis/commareports.com/commareports/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 the Comma API by hand means managing a scoped bearer token, handling the revision and diff model, and running the reviewer and routine flows yourself. Through Jentic you install once, import the Comma API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Comma puts the report id in the URL path (`/reports/{id}`), so a rule can pin your agent to one report: it can read, revise, and comment on that report and nothing else. You choose the operations it may call, so destructive ones like deleting a reviewer or clearing a share password are not included unless you add them.
- **Credential handling:** Your Comma API token 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 'publish an HTML report' or 'diff two revisions', and Jentic returns the matching Comma operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Coda** — Coda builds interactive docs and reports, a comparable authoring surface to Comma.
- **Notion** — Notion stores docs and databases with comments, overlapping with Comma's authoring and commenting.
- **ClickUp** — ClickUp can turn a report's open comments into tracked tasks for the team.

## FAQ

### What authentication does the Comma API use?

The Comma API authenticates with a bearer personal API token in the Authorization header, per its OpenAPI spec, and the token carries granular scopes such as reports read and write. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at call time, so it never enters the agent's prompt, logs, or context.

### Can I diff two revisions of a report with the Comma API?

Yes. Every edit is stored as a revision, so you can list a report's revisions, fetch any single one, and request a line-level diff between two of them. That lets an agent show exactly what changed between versions rather than overwriting content silently.

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

The OpenAPI spec meters AI-heavy work through plan caps and routine usage rather than a fixed request-per-second limit, and exposes a usage endpoint for the current month. Check https://commareports.com for the specific limits on your plan.

### Is there a Comma MCP server?

You don't need an MCP server to give your agent the Comma API. Jentic connects it directly from the API Directory: import it, store your token once, and your agent calls it. Operations are discovered on demand, so your agent's context stays lean instead of loading a separate server's tool definitions.

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

Yes. Write a rule that allows only the read and comment operations on reports, such as fetching a report, listing its revisions, and leaving comments, so the agent can review and annotate but cannot publish share links, delete reviewers, or change connectors. Every call it makes is logged.

### How do I publish a report through Jentic?

Import the Comma API from the Jentic API Directory, store your API token once, and have your agent search Jentic for 'publish an HTML report'. Jentic returns the create-report operation with its input schema so the agent sends the content and reads back the published report. To run it on your own infrastructure, install Jentic One from its GitHub repo.