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.
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.
| Scope | Allows |
|---|---|
reviews:read | Reviews, stats, flags, the agent's queue, Review Monitoring mentions and AI Reputation answers |
reviews:write | Replies, AI drafts, reports to review sites, hiding reviews, review sources, agent and radar actions, publishable keys, webhooks |
companies:read | Your locations, their review sources and settings |
companies:write | Creating and editing locations |
directory:read | The 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.
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
- In Claude Desktop or Claude.ai, open Settings → Connectors and choose Add custom connector.
- Name it Grades.com and paste the server URL below.
- Click Connect, sign in to Grades.com and approve access.
https://mcp.grades.com/mcp
claude mcp add --transport http grades https://mcp.grades.com/mcp
Then run /mcp, pick grades and choose Authenticate.
{
"mcpServers": {
"grades": { "url": "https://mcp.grades.com/mcp" }
}
}
Cursor shows the server as needing a login; click it to sign in to Grades.com.
{
"mcpServers": {
"grades": {
"httpUrl": "https://mcp.grades.com/mcp",
"headers": { "Authorization": "Bearer $GRADES_API_KEY" }
}
}
}
Create a secret key with reviews:read, reviews:write and companies:read for all your businesses and put it in GRADES_API_KEY. Start gemini in a folder you trust and check that /mcp list shows grades Connected. Gemini CLI asks you before it runs a Grades.com tool. Gemini CLI setup and FAQ
- In ChatGPT on the web, open chatgpt.com/plugins, click Add at the top right and choose Add custom MCP server.
- Name it Grades.com, paste the server URL
https://mcp.grades.com/mcpand choose OAuth (no client ID or secret). - Tick I understand and want to continue, click Create as a plugin, then Connect.
- Sign in to Grades.com, choose which businesses ChatGPT may see and click Authorize.
- In a chat, pick Grades.com from the + menu and ask.
Tested on ChatGPT Plus in a web browser: reading reviews, AI Reputation and reply drafts. ChatGPT asks you to confirm before any Grades.com action that changes something; posting a reply from ChatGPT was not part of our test. Menu names change from time to time. ChatGPT setup and FAQ
Any client with remote MCP over Streamable HTTP and OAuth 2.1 can use the sign-in. An agent that can't open a browser sends a secret key instead:
{
"mcpServers": {
"grades": {
"url": "https://mcp.grades.com/mcp",
"headers": { "Authorization": "Bearer gk_live_YOUR_KEY" }
}
}
}
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.
| Platform | What you can do | How 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 draft | Available 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 modules | Add 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 tool | Install 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 clients | Every Grades.com tool, in plain language | Add https://mcp.grades.com/mcp (setup) |
| ChatGPT | Grades.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 |
| WordPress | The Grades Reviews plugin: shortcodes, blocks and a widget for your reviews and showcases | Available 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.
| Event | Sent when |
|---|---|
review.created | A new review arrives |
review.updated | A review is edited, answered, removed or restored |
review.removed | A review is removed from its site (it stays in your archive) |
review.replied | A review gets a reply, from you, the site or the AI Review Agent |
agent.action.pending | The AI Review Agent queued a draft or report for approval |
agent.action.posted | An approved or automatic reply was posted, or a report filed |
source.reconnect_required | A connected account needs a new sign-in |
radar.mention.found | Review Monitoring found new review pages about you |
radar.ai_perception.changed | An AI assistant's view of you changed |
review_request.clicked | A customer clicked a review request |
review_request.visited | A customer opened your review page from a request |
review_request.reviewed | A customer left a review after a request |
review_request.unsubscribed | A 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).
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.
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.
| Address | What it is |
|---|---|
https://app.grades.com/feeds/gk_pub_YOUR_KEY/reviews.rss | RSS 2.0 |
https://app.grades.com/feeds/gk_pub_YOUR_KEY/reviews.atom | Atom 1.0 |
https://app.grades.com/feeds/gk_pub_YOUR_KEY/reviews.json | JSON Feed 1.1 |
https://app.grades.com/feeds/gk_pub_YOUR_KEY/summary.json | Average rating, total reviews, totals per site, your grade, the badges you hold and your profile address |
Add options to the address:
| Option | What it does |
|---|---|
sites | Only these sites, comma-separated, for example sites=google,facebook |
min_rating | The lowest star rating to include, 1 to 5 |
since | Only reviews from this date on, for example since=2026-10-01 |
limit | How many reviews, 1 to 200 (50 if you leave it out) |
all_locations | 1 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.
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
429withRetry-Afterwhen 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.