ReviewComet API

Every call carries your key in an Authorization header:

Authorization: Bearer ck_live_EXAMPLEKEY00000000000000000000000000000

An X-API-Key header holding the bare key does the same job, and either form works. Use whichever your HTTP client makes easy.

The base URL for every path in this reference is https://api.reviewcomet.com, so a first call looks like this:

curl "https://api.reviewcomet.com/v1/reviews?limit=5" \
  -H "Authorization: Bearer ck_live_EXAMPLEKEY00000000000000000000000000000"

A key is 32 random bytes behind a cosmetic prefix, and only its hash is stored. The full value therefore exists in exactly 1 response body, once: copy it when it is shown, because ReviewComet cannot show it again. No key call ever answers a cookie, and a key never reaches the screens a person signs in to.

A call with no key, or with a key that is unknown, revoked or expired, answers 401:

{
  "error": {
    "code": "unauthorized",
    "message": "This endpoint needs an API key."
  }
}

A key that is real but does not reach this far answers 403, and the message says which limit it ran into:

{
  "error": {
    "code": "forbidden",
    "message": "This key needs one of: reviews:act."
  }
}

There is 1 API key, and 2 things decide what you can do with it.

• Your account. A key is minted on an account and reaches exactly as far as that account does. A key on a single location reaches that location. A key on an agency account also reaches the client locations on its book, which is what the Clients group is for. A key on the platform's own account reaches everything. You do not choose this and there is nothing to switch on: it already follows from who you are.
• The scopes you gave it. On the Developers screen you tick exactly what this key may do: read reviews, act on them, read sources and locations, read or write rules, read saved replies, usage and events, manage outbound webhooks, read or write clients, allocate credits.

Beside the scopes you can pin a key to particular locations, give it an expiry date, and cap how many billable actions it may take in a month. A spent cap answers 429 key_cap_reached and clears with the billing cycle.

Reaching past any of these is 1 answer and never a surprise: 403 with the code forbidden, and a message naming which limit it was. There are 3 of them:

• This key needs one of: reviews:act. A missing scope, naming every scope that would have done.
• That location is not in this key's allowlist. A location the key is not pinned to.
• That account is not yours. An account this key's own account does not reach.

Nothing else changes across any of them: the same key, the same header, the same base URL.

Requests are counted per key in fixed windows of 60 seconds, with reads and writes counted separately. A write is also a read, so it counts against both, and the tighter of the 2 is what a refusal tells you about.

Every successful answer carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset. A refusal carries a Retry-After header in seconds beside this body:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 34 seconds.",
    "retry_after": 34
  }
}

Back off on the header rather than on a guess. A retry that ignores it spends the next window on the same refusal:

async function call(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status !== 429 || attempt >= 5) return res;
  const wait = Number(res.headers.get("retry-after") ?? 1);
  await new Promise((done) => setTimeout(done, wait * 1000));
  return call(url, init, attempt + 1);
}

The budget covers the automation endpoints, the Clients endpoints, the assistant endpoint, and the provisioning endpoints, which are metered at the platform tier. An assistant message costs 1 read whatever it goes on to do, and the write it dispatches is counted once, where the write is.

Every list is a keyset walk on (created_time, id) or (created_at, id), newest first. That is what stops a page skipping or repeating a row when new rows land mid-walk, which an offset cannot do. 2 query parameters drive it:

• limit, between 1 and 200, defaulting to 50.
• cursor, the opaque value the previous page handed back.

Every list answers the same envelope:

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOS0xMlQwOTo0MToxOC4wMDBafGNtdF8x"
}

Walk it by passing next_cursor back as cursor until has_more is false and next_cursor is null:

let cursor = null;
do {
  const url = new URL("https://api.reviewcomet.com/v1/reviews");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const page = await (await fetch(url, { headers })).json();
  handle(page.data);
  cursor = page.next_cursor;
} while (cursor);

Every mutation on the automation and Clients endpoints carries an Idempotency-Key header, and it is required: without one the call is refused with 400 idempotency_key_required before the handler runs.

Idempotency-Key: a2f1c9d4-8b76-4e05-9a31-77c0e4d21b8f

Anything from 8 to 128 URL-safe characters works, and a UUID is the obvious choice. The first call to arrive with a given key stores its exact response bytes, and a replay inside the next 24 hours reads those bytes back with an Idempotent-Replay: true header, without reaching the handler at all.

• A key is scoped to 1 call: the method, the path and the body it first carried. Reuse it on a different endpoint, or with a different body, and the answer is 409 conflict, because replaying the first call's response would be the API doing 1 thing and reporting another.
• A second call while the first is still in flight is refused with 409 conflict as well, so 2 racing retries cannot both proceed.
• A failure is not remembered. If the handler threw, or answered 5xx, the claim is released so the same key can be retried once the cause is fixed. A considered 4xx is stored and replayed.

The provisioning endpoints are the exception: there the header is optional. Send one and it is honoured in full, with the same replay, the same 24-hour window and the same 409 conflict on a different body; send none and the call is never refused for it. The provisioning hook has a second guard of its own, a single claim per event per external_id, which is why a redelivery there is answered as a duplicate rather than provisioning again.

Every refusal in this API has 1 shape:

{
  "error": {
    "code": "validation_failed",
    "message": "message is required."
  }
}

code is the stable half and is what you switch on. message is for a person reading a log and may be reworded at any time, so never match on it. Some refusals carry an extra member the caller is meant to act on: retry_after, credits_remaining, allocated and used, monthly_action_cap.

Every code the public endpoints send:

The assistant endpoint is the 1 place this shape is not used. It speaks JSON-RPC, so its refusals arrive as JSON-RPC errors.

An action taken through this API costs exactly what the same action costs inside the app, and nothing extra. There is no API surcharge and no second meter: a reply your integration sends and a reply somebody sends by clicking in ReviewComet draw on the same balance, at the same rate.

Reads cost nothing at all, and they stay free on an expired plan and an empty wallet. Listing reviews, reading a rule, reading sources, usage or events: none of it touches the balance.

The rate depends on what the action is. A rule action and an AI-generated reply are not priced the same, and the rate for each is the one on your billing screen, which is the single place those numbers are published. The endpoints that charge answer with credits_burned beside the data, read off the ledger row rather than off anything written here, so what you read always agrees with what you were charged.

What never charges: creating, changing or deleting a rule, enabling and disabling one, backtesting one, reading sources, usage or events, and managing outbound webhooks. Configuring automation is free, and the charge lands when the automation acts, exactly as it does for a rule somebody built in the app.

3 separate things can pause actions, and each says so with its own code:

• credits_depleted: the account's credit pool is empty, and a credit pack is the way out.
• allocation_depleted: the client's credit pool for this cycle is spent, and every location of that client draws on it. Under an agency this is reached long before the account's pool is, and it needs a bigger allocation rather than a pack.
• key_cap_reached: the monthly action cap set on this key is spent.

GET /v1/usage is where an integration reads all of it: the cycle, what has been spent, what is left, and the same figures per location.

Subscribe an https endpoint with POST /v1/webhooks and ReviewComet posts each event to it as it happens. Every delivery has the same body:

{
  "id": "whd_3r7t2y5u9i4q8n1v6z0c",
  "type": "review.actioned",
  "created_at": "2026-09-14T10:04:22.000Z",
  "workspace_id": "ws_4q8n1v6z0c3r7t2y5u9i",
  "data": { ... }
}

and these headers:

• x-signature-256: sha256= followed by the hex HMAC-SHA256 of the raw body under your signing secret.
• x-signature-256-previous: the same body signed with the secret you just rotated away. Sent for 24 hours after a rotation and then not at all, so a receiver that has not deployed the new secret keeps working and can watch the window close.
• x-timestamp: when this attempt was made.
• x-delivery-id: the attempt's own id, stable across retries of the same delivery.
• x-event-type: the same value as type in the body, for routing before you parse.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retries. A delivery that does not get a 2xx is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then hourly, and is given up 24 hours after it was queued. Answer 2xx as soon as you have stored the event and do your work afterwards: a slow receiver is a retried receiver.

Once per event. An event keeps its id on every retry and is raised once per version of what it describes (each edit, each reply), so a stored id makes a duplicate free to ignore.

The events. Subscribe to any of review.created, review.updated, review.replied, review.reply_failed, review.actioned, reply.pending_approval, private_feedback.received, source.connected, source.disconnected, source.access_lost, location.created, location.deleted, credits.low, credits.depleted, rule.fired and the 6 client.* lifecycle events, or send ["*"] for all of them. The review events carry ids, stars, site and state, never the review's text: read GET /v1/reviews/:id for the words. An endpoint scoped to some locations hears only about those, and its credits.* events carry no account figures. A Slack destination, set up in your settings, may also take digest.daily, a once-a-day summary.

review.* (but review.actioned), private_feedback.received, reply.pending_approval
  data: review_id, workspace_id, source_id, site, rating (1-5 or null),
        recommendation (positive | negative on a Facebook recommendation, else null),
        is_private_feedback, reply_status, author_name (first name), created_time
  review.updated          + changed (any of "text", "rating", "recommendation")
  review.replied          + replied_at, method (posted | copied), by { kind, name }
  review.reply_failed     + failed_at, error_code
  reply.pending_approval  + reason (draft | platform_hold), queued_at
review.actioned           review_id, action, actor, status, platform, platform_synced, at
source.connected          source_id, workspace_id, site, reconnected
source.disconnected       source_id, workspace_id, site
source.access_lost        source_id, workspace_id, site
location.created/deleted  location_id, name
credits.low/depleted      account_id, workspace_id, allowance, burned, remaining, pct,
                          cycle_start, cycle_end (scoped endpoint: workspace_id, event)
rule.fired                object, plus the rule's own detail
client.*                  the client and its workspace

POST https://api.reviewcomet.com/mcp is a Model Context Protocol server over this same API, so an assistant such as a chat client or an editor can call it as a set of tools. Point your client at that URL with your API key as the bearer token and nothing else is needed: it is stateless, so there is no session to open, no stream to keep and no second credential anywhere.

The plan feature mcp gates the endpoint as a whole. Every tool dispatches to one of the REST paths in this reference using your own key, so the scopes on that key mean here exactly what they mean there, a location outside its allowlist is refused the same way, and an action is metered once rather than twice.

The tools, which appear only when your account and your key's scopes reach them:

• Reviews: reviews_list, reviews_get, reviews_stats, reviews_reply, reviews_mark_replied, reviews_approve, reviews_reject, reviews_draft_reply, reviews_assign, reviews_archive, reviews_unarchive, reviews_flag, reviews_unflag.
• Context: sources_list, locations_list, saved_replies_list, rules_list, rules_backtest, usage_get.
• Clients, on an agency account: clients_list, clients_get, clients_usage, clients_allocate_credits, clients_provision.

A rate limit goes the other way and comes back as a JSON-RPC error carrying retry_after, because the client is mid-conversation and needs to match the refusal to the message it sent.

3 prompts ship with the server: triage_new_reviews, weekly_review_summary and unanswered_low_ratings. Each reads first and asks before it spends a credit.