How do I edit a report I already shared without people seeing the half-finished version?

Publish it on Comma and turn on 'Publish only approved revisions' in the share dialog. View-only readers on the link keep seeing the last revision a reviewer approved. You and your reviewers see the latest draft. When a reviewer clicks Approve on the new draft, readers move to it automatically, on the same URL.

What do readers see before anything has been approved?

The latest version. Staged publishing only holds content back once there is an approved revision to fall back to, and the share dialog says so: 'Nothing approved yet — viewers see the latest version until a reviewer approves one.' Get the first approval before you send the link to the wider audience.

Who sees the draft and who sees the approved version?

The owner and signed-in people opening a link with comment or edit permission see the latest draft, because they are the ones reviewing it. View-only readers, anonymous visitors, password-link visitors and embeds on other sites get the last approved revision.

Does the URL change when a new version is approved?

No. The share link and any embed snippet stay the same. The approval moves a pointer to the newer revision, and the next page load serves it. Old links in emails, Slack and wikis keep working and keep showing approved content.

If someone retracts an approval, does the report go back to the older version?

No. The approved pointer only moves forward. Retracting an approval does not un-ship a revision readers have already seen; the next approval on a newer draft is what moves readers on.

Is staged publishing a security control?

No. It decides what readers are shown, not what they are allowed to read. Someone who can open the report could still get to the draft through the API. To keep content from a person, use private visibility, a share password, or company-domain sharing instead.

Can an agent turn staged publishing on?

Yes. Pass show_approved_only: true to the MCP tool set_report_sharing, or PUT it to /api/v1/reports/:id/share with a token that has the sharing scope. The response includes approved_revision_id so the agent can tell whether readers are on an approved version yet.

Staged publishing: edit a shared report without readers seeing the draft

Sending the link is the easy part. The hard part is the next morning, when the numbers need fixing and the link is already in front of the CFO, the client, or forty people in #metrics.

Most tools give you two bad choices. You can edit the live page, and everyone watching sees your half-finished changes. Or you can publish a second copy, and now there are two links, and some people are reading the old one.

Comma has a third option. The link keeps showing the last approved version while you work on the next one. When a reviewer approves the new draft, readers move to it on the same URL.

How it works

Publish the report. Paste HTML or Markdown, upload a folder, or have an agent call create_report.
Get one approval. Share the link with a reviewer as a commenter. They click Approve next to the report. See how sign-off works.
Turn on staged publishing. In the share dialog, click Publish only approved revisions. The toggle then reads Viewers see the last approved revision.
Send the link to everyone.
Keep editing. Every save makes a new revision. Readers stay on the approved one. Your reviewer sees the draft, comments on it, and approves it when it's right.
Readers move to the new version on their next page load. Same URL, no announcement needed.

Who sees what

Person opening the link	Sees
You (the owner)	Latest draft
Signed-in reviewer on a comment or edit link	Latest draft
View-only reader	Last approved revision
Anonymous visitor on a public link	Last approved revision
Visitor who entered the share password	Last approved revision
Readers of an embed on your docs or wiki	Last approved revision

Reviewers need to see the draft, because reviewing it is their job. Everyone else gets the version someone has already signed off on.

The rules, exactly

Nothing is held back until the first approval. With no approved revision, readers see the latest version. The share dialog says this rather than letting you assume otherwise. Approve first, then send the link.
Approvals move readers forward, never back. The approved pointer only advances. An approval on an older revision can't rewind it, and retracting an approval doesn't un-ship content readers already saw.
The URL never changes. Links in email, Slack, Notion, Confluence and embeds keep working through every version.
Old revisions are kept. Revision history is unlimited on every plan, so you can always see exactly what readers were shown and when.

When it's worth turning on

Client deliverables. The client sees the version you agreed on, not the one you're fixing at 11pm.
Weekly and monthly reports to leadership. The analyst refreshes the numbers, the lead approves, and only then does the update reach the list.
Reports an agent regenerates on a schedule. A routine can rebuild the report every morning. With staged publishing on, nobody outside the review loop sees today's output until a person approves it. That makes overnight automation safe to point at stakeholders.
Public status pages and changelogs where a typo stays up for hours once people read it.
Release gates. QA approves the test or coverage report for the build that ships, and the link the release notes point at shows that run.

What it is not

Staged publishing decides what readers are shown, not what they're allowed to read. The draft is still part of a report they can open, so a determined person with API access could still read it. The point is to keep stakeholders from seeing unfinished numbers, not to keep secrets from an adversary.

If a person must not see the content at all, use the access controls instead: private visibility or a share password, or company-domain sharing.

Turning it on from an agent or the API

Agents use the MCP tool set_report_sharing:

set_report_sharing(report_id: "6f1c…", show_approved_only: true)
→ { show_approved_only: true, approved_revision_id: "a91e…", … }

Over REST, the same field goes to the share endpoint with a token that has the sharing scope:

curl -X PUT https://commareports.com/api/v1/reports/REPORT_ID/share \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "show_approved_only": true }'

approved_revision_id is null until the first approval, which is how an agent can tell readers are still seeing the latest version. To approve, a reviewer (or an agent acting as one) calls set_report_signoff, or POSTs to /api/v1/reports/:id/signoffs. See the API docs and the sharing docs.

A simple pattern for an agent that regenerates a report every day: update the report, call request_review so your agent reviewers leave anchored comments on the new draft, and leave staged publishing on. Readers only move once a person reads the draft and approves it.

Try it

Publish a report, ask a teammate to approve it, turn on Publish only approved revisions, then change a number. Open the link in a private window: it still shows the old number until the new revision is approved.

Create a report →