{
  "openapi": "3.1.0",
  "info": {
    "title": "ClickThisLink SEO/AEO/GEO Checker API",
    "version": "0.1.0",
    "contact": {
      "name": "ClickThisLink",
      "email": "hello@clickthislink.xyz",
      "url": "https://clickthislink.xyz"
    },
    "description": "Score any URL 0-100 for SEO, answer engine optimization and generative engine (AI) visibility, with fix suggestions."
  },
  "servers": [
    {
      "url": "https://clickthislink.xyz"
    }
  ],
  "paths": {
    "/badge.svg": {
      "get": {
        "operationId": "getScoreBadge",
        "summary": "Score badge (SVG). Returns a neutral \"check yours\" badge unless a full-report buyer made their homepage badge public. For sharing a free check, use the share.url field from /api/check",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Exact page URL that was checked",
            "schema": {
              "type": "string"
            },
            "example": "https://example.com/"
          }
        ],
        "responses": {
          "200": {
            "description": "SVG badge",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid url"
          }
        }
      }
    },
    "/share.png": {
      "get": {
        "operationId": "getShareImagePng",
        "summary": "Badge share card (PNG). Neutral card unless a full-report buyer made their homepage badge public",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Exact page URL that was checked",
            "schema": {
              "type": "string"
            },
            "example": "https://example.com/"
          }
        ],
        "responses": {
          "200": {
            "description": "PNG image",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid url"
          }
        }
      }
    },
    "/share.svg": {
      "get": {
        "operationId": "getShareImageSvg",
        "summary": "Badge share card (SVG). Neutral card unless a full-report buyer made their homepage badge public",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Exact page URL that was checked",
            "schema": {
              "type": "string"
            },
            "example": "https://example.com/"
          }
        ],
        "responses": {
          "200": {
            "description": "SVG image",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/optout/token": {
      "post": {
        "operationId": "getOptoutToken",
        "summary": "Site owners (privacy controls): get a verification token to opt a domain out of caching, public badges and share links, or back in",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token and instructions"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/optout/verify": {
      "post": {
        "operationId": "verifyOptout",
        "summary": "Verify the token on the domain and apply opt-out or opt-in",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "optout",
                      "optin"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified and applied"
          },
          "400": {
            "description": "Token not found"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/badge/{domain}.svg": {
      "get": {
        "operationId": "getDomainBadge",
        "deprecated": true,
        "summary": "Legacy: badge for a domain homepage",
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "SVG badge",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/check": {
      "get": {
        "operationId": "checkWebsite",
        "summary": "Check a website for SEO, AEO and GEO / AI visibility (private: results are not published or stored beyond short caches)",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          },
          {
            "name": "render",
            "in": "query",
            "required": false,
            "description": "Ignored. Free checks are raw HTML only; JavaScript rendering is part of the paid full report.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Check results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "final_url": {
                      "type": "string"
                    },
                    "http_status": {
                      "type": "integer"
                    },
                    "checked_at": {
                      "type": "string"
                    },
                    "score": {
                      "type": "integer"
                    },
                    "grade": {
                      "type": "string"
                    },
                    "categories": {
                      "type": "object",
                      "properties": {
                        "seo": {
                          "type": "object",
                          "properties": {
                            "score": {
                              "type": "integer"
                            },
                            "items": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "why": {
                                    "type": "string"
                                  },
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "pass",
                                      "warn",
                                      "fail"
                                    ]
                                  },
                                  "score": {
                                    "type": "number"
                                  },
                                  "weight": {
                                    "type": "number"
                                  },
                                  "detail": {
                                    "type": "string"
                                  },
                                  "fix": {
                                    "type": "string",
                                    "nullable": true
                                  }
                                }
                              }
                            }
                          }
                        },
                        "aeo": {
                          "type": "object",
                          "properties": {
                            "score": {
                              "type": "integer"
                            },
                            "items": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "why": {
                                    "type": "string"
                                  },
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "pass",
                                      "warn",
                                      "fail"
                                    ]
                                  },
                                  "score": {
                                    "type": "number"
                                  },
                                  "weight": {
                                    "type": "number"
                                  },
                                  "detail": {
                                    "type": "string"
                                  },
                                  "fix": {
                                    "type": "string",
                                    "nullable": true
                                  }
                                }
                              }
                            }
                          }
                        },
                        "geo": {
                          "type": "object",
                          "properties": {
                            "score": {
                              "type": "integer"
                            },
                            "items": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "why": {
                                    "type": "string"
                                  },
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "pass",
                                      "warn",
                                      "fail"
                                    ]
                                  },
                                  "score": {
                                    "type": "number"
                                  },
                                  "weight": {
                                    "type": "number"
                                  },
                                  "detail": {
                                    "type": "string"
                                  },
                                  "fix": {
                                    "type": "string",
                                    "nullable": true
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "stats": {
                      "type": "object",
                      "properties": {
                        "words": {
                          "type": "integer"
                        },
                        "text_ratio": {
                          "type": "number"
                        }
                      }
                    },
                    "render": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "ok",
                            "unavailable",
                            "skipped"
                          ]
                        },
                        "reason": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "rendered": {
                      "type": "object",
                      "nullable": true,
                      "description": "Always null on free checks (raw HTML only)."
                    },
                    "page": {
                      "type": "object",
                      "description": "Extracted title, description, h1, h2, questions, paragraphs, links, og_image, schema_types."
                    },
                    "fixes": {
                      "type": "array",
                      "description": "Copy-paste fix snippets, highest impact first. Top 3 free; others locked (full report).",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "impact": {
                            "type": "number"
                          },
                          "why": {
                            "type": "string"
                          },
                          "where": {
                            "type": "string"
                          },
                          "lang": {
                            "type": "string"
                          },
                          "code": {
                            "type": "string",
                            "nullable": true
                          },
                          "tier": {
                            "type": "string",
                            "enum": [
                              "free",
                              "full_report"
                            ]
                          },
                          "locked": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad URL"
          },
          "502": {
            "description": "Target unreachable"
          }
        }
      }
    }
  }
}