{
  "openapi": "3.1.0",
  "info": {
    "title": "MentionAgent Public API",
    "summary": "The open, read-only endpoints behind the MentionAgent free tools.",
    "description": "Three read-only endpoints on mentionagent.ai are open to anyone and need no API key. They back the free SEO tools on the site. Each is rate limited per IP and is not a bulk data source. The rest of the MentionAgent product (prospecting, drafting, sending, follow-up) is driven from the dashboard and Telegram, not from a public API.",
    "version": "1.0.0",
    "contact": {
      "name": "MentionAgent support",
      "email": "support@mentionagent.ai",
      "url": "https://mentionagent.ai/developers/"
    },
    "termsOfService": "https://mentionagent.ai/terms/"
  },
  "servers": [
    { "url": "https://mentionagent.ai", "description": "Production" }
  ],
  "externalDocs": {
    "description": "MentionAgent developer and agent resources",
    "url": "https://mentionagent.ai/developers/"
  },
  "tags": [
    { "name": "Authority", "description": "Domain authority lookups used by the free tools." },
    { "name": "Site", "description": "Public counters published by MentionAgent." }
  ],
  "paths": {
    "/api/domain-rating": {
      "get": {
        "operationId": "getDomainRating",
        "summary": "Look up a domain's Ahrefs Domain Rating",
        "description": "Proxies the free Ahrefs Domain Rating endpoint, which sends no CORS headers of its own. Accepts a bare domain, a www host or a full URL, and normalizes it to a registrable hostname before the lookup. One domain per request.",
        "tags": ["Authority"],
        "parameters": [
          {
            "name": "target",
            "in": "query",
            "required": true,
            "description": "Domain, host or URL to rate. \"example.com\", \"www.example.com\" and \"https://example.com/page\" all resolve to example.com.",
            "schema": { "type": "string" },
            "example": "ahrefs.com"
          }
        ],
        "responses": {
          "200": {
            "description": "The domain's rating.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["domain", "domainRating"],
                  "properties": {
                    "domain": { "type": "string", "description": "The normalized hostname that was rated." },
                    "domainRating": { "type": "number", "minimum": 0, "maximum": 100, "description": "Ahrefs Domain Rating. Not the same scale as Open PageRank." }
                  }
                },
                "example": { "domain": "ahrefs.com", "domainRating": 91 }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamFailed" }
        }
      }
    },
    "/api/pagerank": {
      "get": {
        "operationId": "getPageRank",
        "summary": "Look up Open PageRank scores",
        "description": "Proxies Open PageRank so the API key stays off the client. Up to 10 domains per request, 10 requests per IP per hour. Open PageRank is a 0 to 10 scale and is not comparable to Domain Rating.",
        "tags": ["Authority"],
        "parameters": [
          {
            "name": "domains[]",
            "in": "query",
            "required": true,
            "description": "Repeat the parameter once per domain. Maximum 10 per request.",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "maxItems": 10,
              "items": { "type": "string" }
            },
            "example": ["ahrefs.com", "moz.com"]
          }
        ],
        "responses": {
          "200": {
            "description": "The Open PageRank response, passed through unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status_code": { "type": "integer" },
                    "response": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "domain": { "type": "string" },
                          "page_rank_decimal": { "type": "number", "minimum": 0, "maximum": 10 },
                          "rank": { "type": "string" },
                          "status_code": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamFailed" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getPublicStats",
        "summary": "Public MentionAgent counters",
        "description": "The two counters published on the MentionAgent homepage, computed from the production database and cached for 10 minutes.",
        "tags": ["Site"],
        "responses": {
          "200": {
            "description": "Current counters.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["editorsPitched", "blogsResearched"],
                  "properties": {
                    "editorsPitched": { "type": "integer", "description": "Distinct contacts that have been sent at least one pitch." },
                    "blogsResearched": { "type": "integer", "description": "Prospect blogs researched across all workspaces." }
                  }
                }
              }
            }
          },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "description": "A message written for a person, not a machine-readable code." }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "A required parameter is missing or malformed.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Per-IP rate limit reached. Back off and retry later.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "UpstreamFailed": {
        "description": "The upstream data provider could not be reached.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unavailable": {
        "description": "The endpoint is temporarily unavailable.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}