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

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.

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.

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 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.

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 recovery_cases.
4. Show me what needs my attention: pending approvals, new negative reviews and open recovery cases.
Docs: https://www.grades.com/developers

Claude Desktop Claude Code Cursor ChatGPT Your own agent

https://mcp.grades.com/mcp

claude mcp add --transport http grades https://mcp.grades.com/mcp

{
  "mcpServers": {
    "grades": { "url": "https://mcp.grades.com/mcp" }
  }
}

{
  "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 removal reports, review sources, the review agent, Review Radar and AI Reputation, the Competitor Map, locations and review pages. Setup and example questions →

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.

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.

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.

Webhooks

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

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.

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));
}

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.

Add options to the address:

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). 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; 240 MCP tool calls per user every 10 minutes. 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.