{"openapi":"3.1.0","info":{"title":"MentionedOn public API","version":"2.0.0","description":"MentionedOn's public HTTP surface: the Model Context Protocol endpoint, the anonymous leaderboard lookup (REST and A2A) and the health probe. Account data is reached only through MCP with OAuth; every other /api route is first-party only. Use an MCP client for /mcp; this document describes the HTTP envelope, not the individual tools (see https://mentioned-on.com/.well-known/mcp/server-card.json or call tools/list).","contact":{"email":"hello@mentioned-on.com","url":"https://mentioned-on.com/support"},"termsOfService":"https://mentioned-on.com/terms"},"externalDocs":{"url":"https://mentioned-on.com/developers/mcp","description":"MCP setup, tools and safety boundaries"},"servers":[{"url":"https://mentioned-on.com"}],"paths":{"/mcp":{"post":{"operationId":"mcpRequest","summary":"Send an MCP JSON-RPC request (Streamable HTTP, stateless)","description":"Stateless Streamable HTTP: each POST carries one JSON-RPC 2.0 message or batch and gets a JSON response (no session, no long-lived event stream). initialize, tools/list and the three public evidence tools need no credentials. Business tools need an OAuth access token for the resource https://mentioned-on.com/mcp; without one they return an MCP error result carrying a WWW-Authenticate challenge. Server-to-server requests may omit Origin; browser requests are accepted only from allowlisted origins.","security":[{},{"oauth2":["brands:read"]},{"oauth2":["website:write"]}],"parameters":[{"name":"MCP-Protocol-Version","in":"header","required":false,"schema":{"type":"string"},"example":"2025-06-18"}],"requestBody":{"required":true,"description":"JSON-RPC 2.0 request, notification or batch, at most 131072 bytes.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcMessage"},{"type":"array","items":{"$ref":"#/components/schemas/JsonRpcMessage"}}]},"example":{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}}}},"responses":{"200":{"description":"JSON-RPC response (or batch of responses).","content":{"application/json":{"schema":{"type":["object","array"]}}}},"202":{"description":"Accepted: the body held only notifications or responses."},"400":{"description":"JSON-RPC error object (the request was refused before reaching the MCP server).","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"403":{"description":"Host or Origin is not allowed.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"406":{"description":"Accept must include application/json and text/event-stream.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"413":{"description":"Request body is too large.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"415":{"description":"Content-Type must be application/json.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"500":{"description":"Internal MCP server error.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}},"get":{"operationId":"mcpGet","summary":"Not supported: this endpoint has no GET event stream","responses":{"405":{"description":"POST requests only (Allow: POST, OPTIONS).","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}},"options":{"operationId":"mcpPreflight","summary":"CORS preflight for allowlisted browser origins","responses":{"204":{"description":"Preflight accepted."},"403":{"description":"JSON-RPC error object (the request was refused before reaching the MCP server).","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}}},"/api/public/leaderboard":{"get":{"operationId":"getPublicLeaderboard","summary":"Look up one published AI leaderboard (anonymous, read-only)","description":"Returns the stored, dated report behind a mentioned-on.com/top/{vertical}/{city} page: which local businesses AI assistants named, with mention counts (equal counts share a rank). Reads the stored copy only: no scan, no model call, no account, no cost. Counts are model output, not a quality ranking.","parameters":[{"name":"vertical","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,64}$"},"example":"plumbers"},{"name":"city","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,64}$"},"example":"sacramento-ca"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"The published leaderboard.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicLeaderboard"}}}},"400":{"description":"limit out of range.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"const":"invalid_limit"},"max":{"type":"integer"}}}}}},"404":{"description":"Unknown trade/city pair, or nothing published for it yet.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"enum":["unknown_leaderboard","not_published"]}}}}}}}}},"/a2a":{"post":{"operationId":"a2aSendMessage","summary":"A2A agent: the same leaderboard lookup over JSON-RPC (anonymous)","description":"A2A 1.0 (SendMessage) and 0.3 (message/send) JSON-RPC binding; see the Agent Card at https://mentioned-on.com/.well-known/agent-card.json. Send one data part {\"vertical\", \"city\", \"limit\"}; the answer is one message with a text summary and the same JSON as /api/public/leaderboard. No tasks, streaming or push notifications. Not an MCP tool.","parameters":[{"name":"A2A-Version","in":"header","required":false,"schema":{"type":"string","enum":["1.0","0.3"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcMessage"}}}},"responses":{"200":{"description":"JSON-RPC response with one agent message, or a JSON-RPC error."}}}},"/api/health":{"get":{"operationId":"health","summary":"Liveness and release identity","description":"Unauthenticated. The default probe does not touch the database (db and dbWritable are null). deep=1 also checks Postgres reachability and writability and answers 503 when the database is down or read-only.","parameters":[{"name":"deep","in":"query","required":false,"schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"Deep probe failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"Authorization code with PKCE (S256) and dynamic client registration; metadata at https://mentioned-on.com/.well-known/oauth-authorization-server. A person signs in and approves the connection in a browser.","flows":{"authorizationCode":{"authorizationUrl":"https://mentioned-on.com/oauth/authorize","tokenUrl":"https://mentioned-on.com/oauth/token","refreshUrl":"https://mentioned-on.com/oauth/token","scopes":{"brands:read":"Read your owned businesses, saved visibility captures, monitoring history and saved website fixes.","website:write":"Inspect your saved business websites, prepare fixes from facts you confirm, and verify installed fixes. This saves versions in MentionedOn; it never publishes to your website."}}}}},"schemas":{"JsonRpcMessage":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","integer"]},"method":{"type":"string","examples":["initialize","tools/list","tools/call"]},"params":{"type":"object"}}},"PublicLeaderboard":{"type":"object","required":["scope","vertical","city","pageUrl","measuredAt","leaders"],"properties":{"scope":{"const":"published_public_leaderboard"},"vertical":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"city":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"}}},"pageUrl":{"type":"string","format":"uri"},"measuredAt":{"type":"string","format":"date-time"},"questionCount":{"type":"integer"},"assistantCount":{"type":"integer"},"answerCount":{"type":"integer"},"totalLeaders":{"type":"integer"},"leaders":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"tied":{"type":"boolean"},"name":{"type":"string"},"mentions":{"type":"integer"}}}},"limitations":{"type":"array","items":{"type":"string"}}}},"Health":{"type":"object","required":["ok","buildSha","platform"],"properties":{"ok":{"type":"boolean"},"db":{"type":["boolean","null"],"description":"null when not probed (no deep=1)"},"dbWritable":{"type":["boolean","null"]},"dbProbe":{"type":"string","enum":["skipped","deep"]},"serpapiQuotaUsed":{"type":["integer","null"]},"serpapiQuotaCap":{"type":"integer"},"lastScanAt":{"type":["string","null"],"format":"date-time"},"dbCheckedAt":{"type":["string","null"],"format":"date-time"},"version":{"type":"string"},"buildSha":{"type":"string","description":"Full commit SHA of the deployed build"},"platform":{"type":"string","enum":["cloudflare","vercel","node"]},"deploymentId":{"type":"string"},"billingAccountConfigured":{"type":"boolean"}}}}}}