Page comments let people pin a comment anywhere on a live page, such as a preview site or a landing page, and talk it through in a thread right where they pinned it. Clients and your team comment in the page; your team or an agent answers from the API or the MCP server.
Early access
Page comments are switched on per workspace while they roll out. Ask on the Chirio board to have them turned on for yours. Until then the API answers 403 feature_off.
How it works
Spaces. Every thread belongs to a space, a name you choose such as acme-landing or client:42:site. A person is let into one space at a time, so one client never sees another's threads.
People. Your server vouches for each person with a token that names them, their role and their space. Nobody signs in to Chirio.
Roles. A client sees the space's shared threads, starts threads, answers, and resolves the threads they started. A team member also sees team-only threads and resolves any thread.
Answers. Your key answers as a person you name, by default the workspace owner's own profile. A via: "claude" answer shows a via Claude mark next to the name.
Comments are free: no units. A person can write 30 comments a minute.
On a page most visitors should never pay for, use the loader instead. It downloads the widget only in a browser that holds a comments token:
Attribute
Effect
data-lang
en or hu
data-accent
colour of pins and comment mode
data-solid="accent"
buttons in the accent colour
data-token-url
your route that returns the token
In the page, C starts comment mode, H hides or shows the toolbar and Esc leaves. From your own code: window.ChirioComments.identify(token), .start(), .stop(), .signOut() and .refresh().
Vouch for a person
Your server asks for a token with your API key:
A token lasts 12 hours unless you pass hours, up to 30 days. Hand it to the page in one of three ways:
A link to the page ending in #chirio-comments=<token>. The widget keeps it for that site and takes it out of the address. This is how a client's preview site on another domain gets one.
data-token-url on the script tag: the widget asks your server, with cookies, and expects { "token": "…" }, or a 401 or 204 for someone who may not comment.
window.ChirioComments.identify(token) from your own code.
Keep the API key on your server. Never put it in a page.
Comment on any site with the bookmarklet
The dashboard's Comments page has a bookmarklet. Drag it to your bookmarks bar, open any page and click it: the widget loads on that page as you, without a change to the site. The same page lists your open threads, the ones waiting for an answer first, and gives you the script tag to copy.
Who sees a thread
Visibility
Who sees it
all
everyone in the space
team
the team, never a client
claude
its writer and your API key only
A claude thread is a note for your agent. A team member leaves it on the page, and no client or other team member ever sees it. Claude finds these notes with list_page_comments and visibility: "claude", does the work, answers on the pin and resolves it. Notes for Claude have their own early-access switch.
Live cursors
With live cursors on, people reviewing the same page see each other's cursors and names, and a new pin or answer reaches everyone at once instead of on the next refresh. Positions go out only while someone else is on the page. Live cursors have their own early-access switch.
Answer from your server
Call
What it does
GET /api/v1/page-comments
threads, newest activity first
GET /api/v1/page-comments/:id
one thread with its pin
POST /api/v1/page-comments/:id/comments
answer in a thread
POST /api/v1/page-comments/:id
resolve, reopen or change visibility
The list takes space, url, visibility, status (open, resolved or all), needsReply=true, limit and before. Each thread carries its page address and its pin: the element's CSS selector and text, where on the page it sits and the viewport it was left in. Page through with the nextBefore the previous answer gave.
needsReply=true is the queue: threads where a person wrote last. An answer from your key, or resolving the thread, takes it out.
Pass author: { id, name, avatarUrl } to answer as someone other than the workspace owner.
For agents
The MCP server has list_page_comments, get_page_comment, reply_to_page_comment and update_page_comment. Answers go out under the owner's own name with the via Claude mark, so an agent should write as the owner would and never promise what the owner has not.
Feedback pins on boards
The same pin-and-talk review works for your users on a feedback board: the board widget's pin mode turns a click on an element into a board post with a screenshot of that spot.