Developers

Connector & API documentation

Last updated October 2026 · v1.0.0

What this is

RivalSnapshot maintains refreshed snapshots of local service markets in the United States: for a trade (say, pest control) in a town, who the real top-3 competitors are, how the market is sized, and whether AI assistants name a given business. AI assistants and agents can query those snapshots directly. Nothing is scraped live on request; every answer comes from a stored snapshot with its refresh date attached.

Endpoints

Remote MCP (Streamable HTTP): POST https://rivalsnapshot.com/api/mcp — JSON-RPC 2.0; supports initialize, notifications/initialized, ping, tools/list and tools/call, singly or batched. Responses are JSON; the server is stateless and does not open SSE streams. GET on the same URL returns a machine-readable description.
REST: GET https://rivalsnapshot.com/api/market?trade=&town=&state= (market picture) and ?list=1 (mapped markets). Same data, same limits.
OpenAPI 3.1: https://rivalsnapshot.com/openapi.json

Tools

Tool	Type	Inputs	Returns	Notes
`get_market`	read	trade, town, state (2-letter, default NJ)	market size, average rating and review count, the credible top-3 Map Pack, top competitors, AI-visibility verdict	market_not_mapped when the market is not built yet
`list_markets`	read	optional trade, state, limit	mapped markets with refresh count and freshness	capped at 200 rows, newest first
`get_competitors`	read	trade, town, state	the top-3 Map Pack plus the top competitors (name, rating, reviews, website)	free tier; the full roster ships in a purchased report
`check_ai_visibility`	read	business_name, trade, town, state	whether AI currently names that business, who is named, when the market was last polled	not_polled when the market has no AI-visibility poll yet
`order_report`	write, sensitive	trade, town, state, optional email and plan	a prefilled checkout URL with requires_user_confirmation: true	requires X-API-Key; creates nothing and charges nothing — the user completes checkout on rivalsnapshot.com

Every tool result carries structuredContent (the JSON object) and a text block with the same JSON. A market that is not found is reported inside the result (ok: false with error: "market_not_mapped" or "not_polled"), not as a protocol error, so an assistant can explain it to the user.

Authentication and rate limits

Read tools need no credentials. Send an optional X-API-Key header to identify your integration: without a key, callers get 60 requests per minute per IP; with a valid key, 600 per minute. order_report always requires a valid key and answers JSON-RPC error -32001 without one. Rate-limited calls return HTTP 429 with JSON-RPC error -32000. Keys are issued by hand; write to support@rivalsnapshot.com.

Scopes: market:read (all read tools) and report:order (order_report).

Example

POST /api/mcp
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"get_market",
           "arguments":{"trade":"tree service","town":"Toms River","state":"NJ"}}}

Ordering a report

order_report is a sensitive write and should only be called after the user confirms. It returns a link to the order form with the market prefilled. The assistant should show the user that link; the order exists, and payment happens, only once the user submits the form and completes Stripe checkout themselves.

Data handling

Read requests carry only the query (trade, town, state, optionally a business name); they are not stored beyond rate-limit logs that hold no user identifier and expire within 30 days. Details are in the privacy policy. Coverage is US markets only. Support: support@rivalsnapshot.com · Security: security@rivalsnapshot.com · Terms.