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.
Company login and API access
When a workspace requires SSO, integration tokens are currently blocked, including member creation and removal. Keep SSO optional if your workflow depends on the REST API. Creating a member through this API does not approve them for SSO or create an SSO session. See Company login and API provisioning for the supported onboarding flow.
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.
Each project returned by GET /domains carries labels, the labels it has on
the dashboard's projects list, each { id, name } (an empty array when it has
none). Use them to tell projects apart in your own system, for example
White label. The same labels arrive as projectLabels in every
webhook payload.
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.