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.

Was this page helpful?