{
  "components": {
    "schemas": {
      "Comparison": {
        "properties": {
          "category": {
            "description": "Criteres, poids, FAQ et metadonnees du comparatif",
            "type": "object"
          },
          "country": {
            "type": "string"
          },
          "freshness": {
            "description": "Date de derniere mise a jour des donnees",
            "type": "string"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/Option"
            },
            "type": "array"
          },
          "lang": {
            "type": "string"
          },
          "license": {
            "type": "string"
          },
          "markdown_url": {
            "format": "uri",
            "type": "string"
          },
          "neutral": {
            "description": "Sujet traite SANS classement (religions, partis...)",
            "type": "boolean"
          },
          "notice": {
            "type": "string"
          },
          "query": {
            "description": "La demande d'origine",
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "unranked": {
            "description": "Liste non classee faute de donnees comparables",
            "type": "boolean"
          },
          "url": {
            "description": "La page HTML equivalente",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "title",
          "lang",
          "country",
          "url",
          "items"
        ],
        "type": "object"
      },
      "Option": {
        "properties": {
          "link_url": {
            "description": "Destination publique de l'option. Peut etre un lien remunere - voir /mentions-legales.",
            "format": "uri",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "non_note": {
            "description": "true quand aucun critere n'a pu etre note faute de donnee. `score` est alors absent, et l'option figure en fin de liste sans que cela signifie qu'elle est mauvaise.",
            "type": "boolean"
          },
          "provider": {
            "type": "string"
          },
          "score": {
            "description": "Note sur 100. ABSENTE si l'option n'a produit aucun sous-score : voir `non_note`. Une option sans donnee comparable n'est pas notee 0, elle n'est pas notee.",
            "type": "number"
          },
          "source_url": {
            "description": "D'ou viennent les valeurs",
            "format": "uri",
            "type": "string"
          },
          "subscores": {
            "additionalProperties": {
              "type": "number"
            },
            "type": "object"
          },
          "values": {
            "description": "Valeur par critere",
            "type": "object"
          },
          "verified": {
            "description": "Au moins une source TIERCE atteste cette option",
            "type": "boolean"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      }
    }
  },
  "externalDocs": {
    "description": "Méthodologie",
    "url": "https://comparefairly.com/methodologie"
  },
  "info": {
    "contact": {
      "url": "https://comparefairly.com/contact"
    },
    "description": "Chaque comparatif est servi en trois representations a la MEME adresse : HTML pour un lecteur, `.json` pour un agent, `.md` pour une lecture suivie. Chaque valeur porte l'adresse de la source d'ou elle vient. La citation avec lien est autorisee ; l'aspiration du catalogue est limitee par un quota et ne l'est pas (voir /llms.txt).",
    "license": {
      "name": "Conditions d'usage",
      "url": "https://comparefairly.com/mentions-legales"
    },
    "summary": "Comparatifs neutres et sourcés, lisibles par une machine.",
    "title": "CompareFairly",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/llms.txt": {
      "get": {
        "operationId": "getUsagePolicy",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Texte"
          }
        },
        "summary": "Conditions d'usage pour les agents"
      }
    },
    "/mcp": {
      "post": {
        "description": "Trois outils : `search_comparisons`, `get_comparison`, `list_categories`. Aucune authentification. Fiche du registre officiel : com.comparefairly/comparefairly.",
        "operationId": "mcp",
        "responses": {
          "200": {
            "description": "Reponse JSON-RPC"
          }
        },
        "summary": "Point de terminaison MCP (JSON-RPC 2.0, streamable-http)"
      }
    },
    "/sitemap-comparatifs.xml": {
      "get": {
        "operationId": "listComparisons",
        "responses": {
          "200": {
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Sitemap XML"
          }
        },
        "summary": "Toutes les adresses de comparatifs"
      }
    },
    "/{lang}/{country}/{slug}.json": {
      "get": {
        "description": "Options classees, criteres, sous-scores, et pour chaque valeur l'URL de sa source. `unranked: true` signale une liste volontairement NON classee, faute de donnees comparables - ne pas en deduire un ordre.",
        "operationId": "getComparisonJson",
        "parameters": [
          {
            "description": "Code langue ISO 639-1 (fr, en, de...)",
            "in": "path",
            "name": "lang",
            "required": true,
            "schema": {
              "pattern": "^[a-z]{2}$",
              "type": "string"
            }
          },
          {
            "description": "Code pays ISO 3166-1 alpha-2 en MAJUSCULES (FR, GB, US...)",
            "in": "path",
            "name": "country",
            "required": true,
            "schema": {
              "pattern": "^[A-Z]{2}$",
              "type": "string"
            }
          },
          {
            "description": "Identifiant du comparatif, tel que donne par le sitemap",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comparison"
                }
              }
            },
            "description": "Le comparatif"
          },
          "404": {
            "description": "Aucun comparatif a cette adresse dans ce marche"
          },
          "429": {
            "description": "Quota de lecture machine depasse. L'en-tete `Retry-After` donne le delai. Le HTML n'est jamais limite."
          }
        },
        "summary": "Un comparatif complet, en JSON"
      }
    },
    "/{lang}/{country}/{slug}.md": {
      "get": {
        "operationId": "getComparisonMarkdown",
        "parameters": [
          {
            "in": "path",
            "name": "lang",
            "required": true,
            "schema": {
              "pattern": "^[a-z]{2}$",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "country",
            "required": true,
            "schema": {
              "pattern": "^[A-Z]{2}$",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Markdown"
          },
          "429": {
            "description": "Quota de lecture machine depasse"
          }
        },
        "summary": "Le meme comparatif, en Markdown"
      }
    }
  },
  "servers": [
    {
      "url": "https://comparefairly.com"
    }
  ]
}