REST API
The REST API gives your backend direct access to your Simple Commenter account: provision team members and clients, read and update feedback, and mint client login tokens. It is the server-to-server counterpart to the JS API, which runs in the browser.
Authentication
Every request carries an integration token in the X-Integration-Token
header:
curl -H "X-Integration-Token: YOUR_TOKEN" \
"https://www.simplecommenter.com/api/external/domains"
The workspace owner can generate a token in Project → MCP → Local API
tokens, open MCP settings directly, or use
Project settings → Developers → REST API. Tokens carry scoped actions
(read, write, settings); tokens generated from the dashboard have all
three and access the whole account. Copy a new token when it is shown, and
revoke it in settings when it is no longer needed.
For a ChatGPT or Claude remote connection, use the hosted MCP setup
with OAuth and https://www.simplecommenter.com/api/mcp. The REST API base URL
below is not a remote MCP address. Hosted OAuth can restrict projects and
actions without using a local integration token.
Treat the token like a password: it grants access to your whole account. Store it in an environment variable or secrets manager, never in client-side code.
Base URL
https://www.simplecommenter.com/api/external
All endpoints accept and return JSON unless noted. Errors come back as
{ "error": "message" } with a matching HTTP status.
Endpoints
| Area | Endpoint | Documented |
|---|---|---|
| Members | /members |
Members & Clients |
| Clients | /clients |
Members & Clients |
| Client login tokens | /client-token |
Members & Clients |
| Projects | /domains, /domains/{domainId}/settings |
Reference on request |
| Comments | /comments, /comments/{commentId}, /comments/reply, /comments/update, /comments/create |
Feedback operations |
| Account | /account |
Reference on request |
| MCP operations | POST /mcp |
Token-authenticated operation adapter used by the local MCP server |
Addressing projects: endpoints that take a domainId accept the project's
public key (sc_...), its project ID, or the domain name.
Comments returned by /comments and /comments/{commentId} carry a brief
object once a dev brief has been written (null before
that). It holds status, title, summary, optional suggestedFix, kind,
confidence, and generatedAt.
metadata.consoleErrorCount is always present on /comments items. The list
itself, metadata.consoleErrors, comes with include=metadata_full on
/comments and always on /comments/{commentId}: the JavaScript errors
captured on the page before the comment, each { kind, message, source, line, col, at }. See Console errors.
Comment and reply text is Markdown Lite (**bold**, `code`, -
bullet lines) returned as written, with textFormat: "markdown-lite" beside
it; see Formatting.
Rate limits
Rate limits depend on the endpoint. POST /api/external/mcp permits 120
requests per minute per integration token. Hosted OAuth MCP has a separate
120-request-per-minute limit per connection. When an endpoint returns 429,
respect its Retry-After header when supplied and retry with backoff. These MCP
limits are not a shared plan-based API allowance.
When to use which API
- REST API: your server manages the account. Sync your user base as clients, add a member when someone joins your team, pull feedback into your own tooling.
- MCP: an external AI client discovers tools for feedback, exports, reports, and permitted project or team administration.
- JS API: the browser logs a visitor in and controls the widget. For most SaaS setups the JS API alone is enough, because a verified identify creates the client automatically on first sight.