{
  "openapi": "3.2.0",
  "info": {
    "title": "Content Helper",
    "description": "Fetch data from Content Helper reports",
    "termsOfService": "https://ahrefs.com/terms",
    "contact": {
      "name": "Ahrefs",
      "url": "https://ahrefs.com/",
      "email": "support@ahrefs.com"
    },
    "version": "3.0.0"
  },
  "servers": [
    {
      "url": "https://api.ahrefs.com/v3/content-helper",
      "description": "Ahrefs Content Helper"
    }
  ],
  "paths": {
    "/topics": {
      "get": {
        "tags": [ "Topics", "MCP" ],
        "summary": "Topics",
        "description": ">This endpoint consumes a base amount of 1000 units per request, plus 500 units if you request a URL to score.\n\n>The analysis runs on demand against the pages currently ranking for the keyword, so the first request for a keyword takes a few seconds. Results are cached, and repeat requests are served from the cache free of charge.\n\n>Only SERPs Ahrefs has already collected are used, and no new SERP is collected. If we have collected a SERP for the keyword and country in the last 90 days, the endpoint returns a `400` error and no units are consumed.",
        "operationId": "topics",
        "parameters": [
          {
            "description": "The keyword to analyse the SERP for.",
            "required": true,
            "explode": false,
            "schema": { "type": "string" },
            "name": "keyword",
            "in": "query"
          },
          {
            "description": "A two-letter country code (ISO 3166-1 alpha-2).",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ]
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "How many of the top-ranking pages to analyse. Fewer pages make the analysis faster at the cost of breadth.",
            "required": false,
            "explode": false,
            "schema": { "type": "integer", "default": 10 },
            "name": "top_competitors",
            "in": "query"
          },
          {
            "description": "(500 units) A page of your own to score against the same topics, for example a draft you are writing or a page you want to improve. The page is fetched live. Costs additional API units each time (its scoring is not cached).",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "format": "url" },
            "name": "target_url",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output_json_php" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/topics" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/topics" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error response": {
        "properties": { "error": { "type": "string" } },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "topics": {
        "properties": {
          "topics": {
            "items": {
              "properties": {
                "avg_score": {
                  "type": "number",
                  "format": "float",
                  "title": "avg_score",
                  "description": "The mean coverage score of this topic, from 0 to 100, over the pages that could be analysed. A high value means the topic is thoroughly covered by the pages that already rank. Null when none of the pages could be analysed."
                },
                "description": {
                  "type": "string",
                  "title": "description",
                  "description": "What the core topic is about, as identified from the competing pages."
                },
                "pages": {
                  "items": {
                    "properties": {
                      "url": { "type": "string", "format": "url" },
                      "position": { "type": "integer" },
                      "score": { "type": "integer" },
                      "extracts": {
                        "items": { "type": "string" },
                        "type": "array"
                      }
                    },
                    "type": "object"
                  },
                  "type": "array",
                  "title": "pages",
                  "description": "Per-page coverage of this topic: a record with fields `url`, `position` (the page's SERP position), `score` (0-100) and `extracts` (passages from the page that cover the topic). `score` and `extracts` are null and empty for a page whose content could not be retrieved, which is distinct from a page that scored zero."
                },
                "pages_covering": {
                  "type": "integer",
                  "title": "pages_covering",
                  "description": "How many of the analysed pages cover this topic at all (a non-zero score)."
                },
                "serp_date": {
                  "type": "string",
                  "format": "date",
                  "title": "serp_date",
                  "description": "When the analysed SERP was collected."
                },
                "target": {
                  "properties": {
                    "url": { "type": "string", "format": "url" },
                    "score": { "type": "integer" },
                    "extracts": {
                      "items": { "type": "string" },
                      "type": "array"
                    }
                  },
                  "type": [ "object", "null" ],
                  "title": "target",
                  "description": "How the page given as `target_url` covers this topic. Null when `target_url` was not given."
                },
                "topic": {
                  "type": "string",
                  "title": "topic",
                  "description": "The name of the core topic covered by the top-ranking pages."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      }
    },
    "responses": {
      "error_400": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          }
        }
      },
      "error_401": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          }
        }
      },
      "error_403": {
        "description": "Forbidden",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          }
        }
      },
      "error_429": {
        "description": "Too Many Requests",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          }
        }
      },
      "error_500": {
        "description": "Internal Error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error response" }
          }
        }
      }
    },
    "parameters": {
      "output_json_php": {
        "description": "The output format.",
        "required": false,
        "explode": false,
        "schema": { "type": "string", "enum": [ "json", "php" ] },
        "name": "output",
        "in": "query"
      }
    },
    "examples": {},
    "requestBodies": {},
    "headers": {},
    "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } },
    "links": {},
    "callbacks": {},
    "pathItems": {},
    "mediaTypes": {}
  },
  "security": [ { "http": [ "read" ] } ],
  "tags": [ { "name": "Topics" } ],
  "externalDocs": {
    "description": "",
    "url": "https://docs.ahrefs.com/docs/api/v3/"
  }
}