{
  "openapi": "3.2.0",
  "info": {
    "title": "Public",
    "description": "Free endpoints that don't require an Ahrefs subscription, or require a free/public APIv3 key",
    "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/public",
      "description": "Ahrefs Public"
    }
  ],
  "paths": {
    "/crawler-ips": {
      "get": {
        "tags": [ "Crawler", "MCP" ],
        "summary": "Crawler IP addresses",
        "description": ">Requests to this endpoint are free and do not require an API key.",
        "operationId": "crawler-ips",
        "parameters": [ { "$ref": "#/components/parameters/output" } ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/crawler-ips" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/crawler-ips" }
              }
            }
          },
          "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" }
        },
        "security": []
      }
    },
    "/crawler-ip-ranges": {
      "get": {
        "tags": [ "Crawler", "MCP" ],
        "summary": "Crawler IP ranges",
        "description": ">Requests to this endpoint are free and do not require an API key.",
        "operationId": "crawler-ip-ranges",
        "parameters": [ { "$ref": "#/components/parameters/output" } ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/crawler-ip-ranges"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/crawler-ip-ranges"
                }
              }
            }
          },
          "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" }
        },
        "security": []
      }
    },
    "/domain-rating-free": {
      "get": {
        "tags": [ "Domain Rating", "MCP" ],
        "summary": "Domain rating free",
        "description": ">Requests to this endpoint are free, yet require an APIv3 key.\n\n>APIv3 keys are free to generate and use. If you don't have an Ahrefs account, here's how to get the key for free:\n>1. [Sign up](https://ahrefs.com/) for a free Ahrefs account (if you don't have one)\n>2. Generate an API key in [Account settings → API keys](https://app.ahrefs.com/account/api-keys)\n>3. Add it to your requests: `Authorization: Bearer <token>`\n\nUse of this data is subject to the Domain Rating License at http://ahrefs.com/legal/domain-rating-license. Attribution required: \"Domain Rating by Ahrefs\" (https://ahrefs.com/).",
        "operationId": "domain-rating-free",
        "parameters": [
          {
            "description": "The target of the search: a domain or a URL.",
            "required": true,
            "explode": false,
            "schema": { "type": "string", "format": "url" },
            "name": "target",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain-rating-free"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/domain-rating-free"
                }
              }
            }
          },
          "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" }
        }
      }
    },
    "/domain-rating-top-domains": {
      "get": {
        "tags": [ "Domain Rating", "MCP" ],
        "summary": "Domain rating top domains",
        "description": ">Requests to this endpoint are free, yet require an APIv3 key.\n\n>APIv3 keys are free to generate and use. If you don't have an Ahrefs account, here's how to get the key for free:\n>1. [Sign up](https://ahrefs.com/) for a free Ahrefs account (if you don't have one)\n>2. Generate an API key in [Account settings → API keys](https://app.ahrefs.com/account/api-keys)\n>3. Add it to your requests: `Authorization: Bearer <token>`\n\nReturns the top 1M domains ranked by Ahrefs Domain Rating, together with each domain's current Domain Rating.\nUse `from` and `to` to request a range of rank positions. Each request can return up to 250k rows (e.g. `from=1&to=250000`).\n",
        "operationId": "domain-rating-top-domains",
        "parameters": [
          {
            "description": "Rank position to start from.",
            "required": false,
            "explode": false,
            "schema": { "type": "integer", "default": 1 },
            "name": "from",
            "in": "query"
          },
          {
            "description": "Rank position to end at. You can request up to 250k rows at a time.",
            "required": false,
            "explode": false,
            "schema": { "type": "integer", "default": 100 },
            "name": "to",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain-rating-top-domains"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/domain-rating-top-domains"
                }
              }
            }
          },
          "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" }
      },
      "crawler-ips": {
        "properties": {
          "ips": {
            "items": {
              "properties": {
                "ip_address": { "type": "string", "title": "ip_address" }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "crawler-ip-ranges": {
        "properties": {
          "prefixes": {
            "items": {
              "properties": {
                "ipv4Prefix": { "type": "string", "title": "ipv4Prefix" }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "domain-rating-free": {
        "properties": {
          "domain_rating": {
            "properties": {
              "domain_rating": {
                "type": "number",
                "format": "float",
                "title": "domain_rating",
                "description": "Current strength of your target's backlink profile compared to the other websites in our database on a 100-point logarithmic scale."
              },
              "license": {
                "type": "string",
                "format": "url",
                "title": "license",
                "description": "URL of the license terms that apply to use of Domain Rating data."
              }
            },
            "type": "object"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "domain-rating-top-domains": {
        "properties": {
          "domains": {
            "items": {
              "properties": {
                "domain": {
                  "type": "string",
                  "format": "domain",
                  "title": "domain",
                  "description": "Domain name."
                },
                "domain_rating": {
                  "type": "number",
                  "format": "float",
                  "title": "domain_rating",
                  "description": "Current strength of the domain's backlink profile compared to the other websites in our database on a 100-point logarithmic scale."
                },
                "rank": {
                  "type": "integer",
                  "title": "rank",
                  "description": "Position of the domain in the top 1M ranking by Domain Rating (1 = highest)."
                }
              },
              "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": {
        "description": "The output format.",
        "required": false,
        "explode": false,
        "schema": {
          "type": "string",
          "enum": [ "json", "csv", "xml", "php" ]
        },
        "name": "output",
        "in": "query"
      }
    },
    "examples": {},
    "requestBodies": {},
    "headers": {},
    "securitySchemes": {},
    "links": {},
    "callbacks": {},
    "pathItems": {},
    "mediaTypes": {}
  },
  "tags": [ { "name": "Crawler" }, { "name": "Domain Rating" } ],
  "externalDocs": {
    "description": "",
    "url": "https://docs.ahrefs.com/docs/api/v3/"
  }
}