{
  "openapi": "3.1.0",
  "info": {
    "title": "Clarity API",
    "version": "1.0.0",
    "description": "AI visibility and AI-readiness (GEO) tools by Clarity (Whooho). Pay per call with prepaid credits. Also available as an MCP server at /api/mcp.",
    "contact": {
      "name": "Clarity by Whooho",
      "url": "https://clarity.whooho.it/en/contact"
    }
  },
  "servers": [
    {
      "url": "https://clarity.whooho.it"
    }
  ],
  "externalDocs": {
    "url": "https://clarity.whooho.it/en/developers"
  },
  "paths": {
    "/api/v1/geo-audit": {
      "post": {
        "operationId": "geo_audit",
        "summary": "GEO / AI-readiness audit of a website",
        "description": "Checks whether a website can be read, understood and quoted by AI search engines (ChatGPT, Claude, Gemini, Perplexity, Copilot): AI crawlers allowed in robots.txt and not blocked by the firewall, llms.txt and llms-full.txt, sitemap freshness, content readable without JavaScript, Organization schema, snippet directives (nosnippet/noai), trust pages, Open Graph, language. Returns a 0-100 score and every check with its status.\n\nPrice: €0.50 per call, charged to prepaid credits and refunded if the call fails.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Website domain or URL, e.g. \"example.com\" or \"https://www.example.com\""
                  }
                },
                "required": [
                  "url"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolCallResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits (details: price_cents, balance_cents)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or too many concurrent calls",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Daily capacity reached or no models available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/visibility": {
      "post": {
        "operationId": "visibility_check",
        "summary": "AI visibility check for a brand",
        "description": "Asks a question to real AI models with live web search (as a user would) and reports whether the brand is mentioned, how many times, its rank in recommendation lists, which competitors appear and which sources are cited. Available models: chatgpt, gemini. Default: all available models.\n\nPrice: €0.35 per model asked, charged to prepaid credits and refunded if the call fails.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "brand": {
                    "type": "string",
                    "description": "Brand or company name to look for"
                  },
                  "question": {
                    "type": "string",
                    "description": "The question a customer would ask, e.g. \"Best e-bike shops in Milan?\" (5-500 chars)"
                  },
                  "models": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt",
                        "gemini"
                      ]
                    },
                    "description": "Models to ask (max 5). Default: all available"
                  },
                  "competitors": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional competitor names to track (max 10)"
                  },
                  "brand_domain": {
                    "type": "string",
                    "description": "Optional brand website domain, to detect if it is cited as a source"
                  }
                },
                "required": [
                  "brand",
                  "question"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolCallResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits (details: price_cents, balance_cents)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or too many concurrent calls",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Daily capacity reached or no models available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/account": {
      "get": {
        "operationId": "account",
        "summary": "Remaining credits and current prices (free)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools": {
      "get": {
        "operationId": "tools",
        "summary": "Public list of tools, input schemas and prices",
        "responses": {
          "200": {
            "description": "Tools"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key \"clr_...\" from https://clarity.whooho.it/dashboard/api"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        }
      },
      "ToolCallResult": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string"
          },
          "tool": {
            "type": "string"
          },
          "gross_cents": {
            "type": "integer",
            "description": "Euro cents reserved before the call"
          },
          "charged_cents": {
            "type": "integer",
            "description": "Euro cents actually charged (gross minus refunds)"
          },
          "refunded_cents": {
            "type": "integer"
          },
          "balance_cents": {
            "type": "integer",
            "description": "Remaining credits"
          },
          "result": {
            "type": "object"
          }
        }
      }
    }
  }
}