Developers

An open API for your reviews, and an MCP server for your AI

The dashboard runs on the same API you can call. Use a key from your own code, connect an AI client to the MCP server, or show your reviews on your website with a publishable key.

REST API
https://app.grades.com/api/v1
MCP server
https://mcp.grades.com/mcp (Streamable HTTP)
Sign-in
Secret API keys (gk_live_) or OAuth 2.1 with PKCE
Format
JSON in a {data, meta} envelope, errors as RFC 7807 problem details
Rate limits
120 requests a minute per key, 600 a minute per publishable key

REST API v1

Create a key in the dashboard under Connect your AI. A secret key acts as you: it reaches only the locations you are an accepted member of, and only with the scopes you give it. It is shown once and stored as a hash. Lists use cursor pagination, and a company you don't belong to answers 404, so ids can't be probed.

Your account, your locations, and low-rated reviews without a reply
curl -H "Authorization: Bearer gk_live_YOUR_KEY" \
  https://app.grades.com/api/v1/me

curl -H "Authorization: Bearer gk_live_YOUR_KEY" \
  https://app.grades.com/api/v1/companies

curl -G -H "Authorization: Bearer gk_live_YOUR_KEY" \
  https://app.grades.com/api/v1/companies/{company_uuid}/reviews \
  --data-urlencode "max_rating=2" \
  --data-urlencode "has_company_response=false"

Every endpoint, parameter and response is in the API reference, generated from the code. The same API is published as an OpenAPI description (JSON, or YAML) for tools and AI agents.

Animated example: a terminal runs curl against the Grades.com reviews endpoint and gets back a 5-star review without a reply as JSON.

Scopes

A key carries the scopes you pick; an OAuth token carries the ones you approve. A missing scope answers 403 and names the scope it needs.

ScopeAllows
reviews:readReviews, stats, flags, the agent's queue, Review Monitoring mentions and AI Reputation answers
reviews:writeReplies, AI drafts, reports to review sites, hiding reviews, review sources, agent and radar actions, publishable keys, webhooks
companies:readYour locations, their review sources and settings
companies:writeCreating and editing locations
directory:readThe public directory: profiles, search and rankings

MCP server

Add one URL to your AI client and sign in to Grades.com. Your assistant can then read and search reviews, draft replies and post the ones you confirm, work through the AI Review Agent's queue, check what AI assistants say about you and compare you with competitors. Tools act as you: your locations and your scopes, nothing else.

Paste it into Claude, ChatGPT or Cursor. It connects grades.com for you.
What it copies
Set up grades.com in this assistant.
1. Add the grades.com MCP server: https://mcp.grades.com/mcp (Streamable HTTP, OAuth 2.1). Sign in to grades.com when prompted and approve the scopes it asks for.
2. If this client cannot do OAuth, use an API key from https://my.grades.com/connect as a Bearer token instead.
3. Once it is connected, call plan_overview, then reviews_summary_period for the last 30 days, then agent_actions and dispute_cases.
4. Show me what needs my attention: pending approvals, new negative reviews and open Review Disputes cases.
Docs: https://www.grades.com/developers
  1. In Claude Desktop or Claude.ai, open Settings → Connectors and choose Add custom connector.
  2. Name it Grades.com and paste the server URL below.
  3. Click Connect, sign in to Grades.com and approve access.
Server URL
https://mcp.grades.com/mcp

OAuth access tokens last one hour and renew with a rotating refresh token, and the same token works on the REST API. Tool families: reviews and search, replies and reports to review sites (Review Disputes), review sources, the AI Review Agent, Review Monitoring and AI Reputation, the Competitor Map, locations and review pages. Setup and example questions →

Animated example: in Claude, someone asks which reviews still need a reply; Claude searches Grades.com, lists three reviews of a dental practice and drafts a reply to the 3-star one.

Let your AI set it up

The MCP server also has tools to create a key for an integration and to fetch its setup guide. So you can tell your assistant "connect Grades.com to Make" (or Zapier, n8n, Slack, Google Chat): it creates a key scoped to that tool, shows it once, and walks you through the rest. Pages per tool: Integrations.

Animated example: someone asks Claude to set up Make; Claude creates an API key scoped to Make, shows it once with a Copy button and lists the three steps in Make.

Integrations

Every integration in one place, with what each one does: Integrations.

Reports: the Google Sheets add-on and the Looker Studio connector read with a key that has companies:read and reviews:read.

Reporting and BI tools (Power BI, Excel, Tableau, Supermetrics, BigQuery and agency dashboards) : use Grades.com in your reporting tool.

Connect Grades.com to the tools you already use without writing code. Every platform signs in with a secret key (reviews:read, reviews:write, companies:read) and lets you pick the business, so one agency or multi-location key covers every location. Triggers use the webhooks below, on Pro and Premium.

PlatformWhat you can doHow to start
Zapier New review, review removed, reply posted, agent draft waiting, review page found, review request clicked; send a review request, add a contact, reply to a review, approve a draftAvailable now by invite: join the Grades.com app on Zapier (listed in the Zapier directory after review); get your API key
Make The same triggers as instant triggers, and the same actions and searches as modulesAdd the Grades.com app in a Make scenario; get your API key
n8n A Grades.com node (reviews, replies, the AI Review Agent, review requests, contacts) and a Grades.com Trigger node; the node also works as an AI agent toolInstall the community node n8n-nodes-grades in Settings > Community Nodes (npm package); a verified listing on n8n Cloud comes later; get your API key
Claude, Cursor and other MCP clientsEvery Grades.com tool, in plain languageAdd https://mcp.grades.com/mcp (setup)
ChatGPTGrades.com as a custom MCP server in ChatGPT on the web: ask about reviews and draft replies (tested on ChatGPT Plus)Custom MCP server: setup
WordPressThe Grades Reviews plugin: shortcodes, blocks and a widget for your reviews and showcasesAvailable as a download: Download the plugin (.zip). Version 1.6.2. Also submitted to the WordPress.org plugin directory and in review there; once it is listed, updates come from WordPress.org.

Building your own? GET /api/v1/webhooks/events lists every event with an example, and GET /api/v1/webhooks/samples?event=&company= returns sample payloads in the exact delivery shape (both in the API reference).

Webhooks

Register up to 25 HTTPS endpoints per location with POST /api/v1/webhooks (scope reviews:write). The secret (whsec_...) is shown once.

EventSent when
review.createdA new review arrives
review.updatedA review is edited, answered, removed or restored
review.removedA review is removed from its site (it stays in your archive)
review.repliedA review gets a reply, from you, the site or the AI Review Agent
agent.action.pendingThe AI Review Agent queued a draft or report for approval
agent.action.postedAn approved or automatic reply was posted, or a report filed
source.reconnect_requiredA connected account needs a new sign-in
radar.mention.foundReview Monitoring found new review pages about you
radar.ai_perception.changedAn AI assistant's view of you changed
review_request.clickedA customer clicked a review request
review_request.visitedA customer opened your review page from a request
review_request.reviewedA customer left a review after a request
review_request.unsubscribedA customer opted out of review requests

Each delivery carries X-Grades-Event, X-Grades-Delivery (use it to drop duplicates) and X-Grades-Signature: t=<unix seconds>,v1=<hex>, where the hex is the HMAC-SHA256 of <t>.<raw body> with your secret. Answer with any 2xx within 5 seconds; other answers are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours (the last retry is about 15 hours after the first try).

Check a delivery (Node.js)
import crypto from 'node:crypto';

// rawBody: the request body exactly as received; header: X-Grades-Signature
export function isFromGrades(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((pair) => pair.split('=')));
  if (!parts.t || !parts.v1 || Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  return expected.length === parts.v1.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Animated example: a server log receives a signed review.created webhook from Grades.com, checks the signature and answers 200.

Public reviews API

Show your reviews on your own website with one request, in your own design. A publishable key (gk_pub_...) reads only the reviews you haven't hidden, so it can sit in a web page; you can limit which websites may use it from a browser. /public/reviews filters by rating and site, newest or best first; /public/summary returns the averages with a schema.org AggregateRating ready for JSON-LD. Answers are cached for 5 minutes with ETags, CORS is open, and no cookies are involved.

Six best reviews, 4 stars and up
curl "https://app.grades.com/api/v1/public/reviews?key=gk_pub_YOUR_KEY&min_rating=4&limit=6&sort=best"

Review feeds

Every business has review feeds that any tool reading RSS can use, with no code and no secret key. The address carries a publishable key (gk_pub_...), created in the dashboard under Connect your AI or Review Marketing; GET /v1/companies/{uuid}/feeds returns the four addresses for a business, ready to copy.

AddressWhat it is
https://app.grades.com/feeds/gk_pub_YOUR_KEY/reviews.rssRSS 2.0
https://app.grades.com/feeds/gk_pub_YOUR_KEY/reviews.atomAtom 1.0
https://app.grades.com/feeds/gk_pub_YOUR_KEY/reviews.jsonJSON Feed 1.1
https://app.grades.com/feeds/gk_pub_YOUR_KEY/summary.jsonAverage rating, total reviews, totals per site, your grade, the badges you hold and your profile address

Add options to the address:

OptionWhat it does
sitesOnly these sites, comma-separated, for example sites=google,facebook
min_ratingThe lowest star rating to include, 1 to 5
sinceOnly reviews from this date on, for example since=2026-10-01
limitHow many reviews, 1 to 200 (50 if you leave it out)
all_locations1 on a head-office key includes every location; each item then carries its location

Items are the reviews your widgets could show, newest first: no Yelp text, nothing you hid or that was removed from its site, and no clinical terms for a healthcare business. Each item has a stable id (the review's own), a title such as "★★★★★ on Google by Jane D.", the site and the rating as extra fields (grades:site and grades:rating in XML, _grades in JSON), so a reader or trigger sees every review once. Feeds refresh at most every 15 minutes and allow 120 requests a minute per key. Revoking the key stops the feed (404) within 15 minutes.

The ten newest reviews rated 4 stars and up
curl "https://app.grades.com/feeds/gk_pub_YOUR_KEY/reviews.json?min_rating=4&limit=10"

In Zapier, Make or n8n, use the RSS trigger with the .rss address. In Slack, run /feed subscribe with it in a channel. In Google Sheets, use =IMPORTFEED("<the .atom address>", "items", TRUE, 50), and click Allow access the first time. For something that must fire the moment a review arrives, use the webhooks.

Limits and keys

  • 120 requests a minute per secret key or OAuth sign-in; 600 a minute per publishable key. Up to 240 MCP tool calls every 10 minutes per connection (each API key or connected AI app), and up to 960 per user across all of their connections. The API answers 429 with Retry-After when you go over.
  • Up to 50 secret keys per user, each with an optional expiry date. Revoking a key takes effect at once.
  • Disconnecting an AI client ends its sign-in; changing your password ends all of them.
  • Replies, reports and setting changes made through the API or MCP are recorded with the user and the credential that made them.

How we handle the data your keys reach: Security.