{
  "openapi": "3.0.3",
  "info": {
    "title": "Cala Turquoise API",
    "version": "1.0.0",
    "description": "API JSON statique, publique et en lecture seule. Sans authentification. Recherche côté agent. Les données sont celles du guide, pas des informations en temps réel. La date de génération de l’API ne constitue pas une nouvelle vérification. Consulter les sources datées et revérifier les informations susceptibles de changer."
  },
  "servers": [
    {
      "url": "https://cala-turquoise.pages.dev/api/v1"
    }
  ],
  "security": [],
  "paths": {
    "/index.json": {
      "get": {
        "operationId": "getApiIndex",
        "summary": "Découvrir l’API, ses dates et ses limites.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Données du guide en français.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Ressource absente. Le corps peut être HTML."
          }
        }
      }
    },
    "/categories.json": {
      "get": {
        "operationId": "getCategories",
        "summary": "Lister les catégories et les rubriques avec leurs URL.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Données du guide en français.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Ressource absente. Le corps peut être HTML."
          }
        }
      }
    },
    "/places.json": {
      "get": {
        "operationId": "getPlaces",
        "summary": "Catalogue complet ; recherche et filtrage côté agent.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Données du guide en français.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "404": {
            "description": "Ressource absente. Le corps peut être HTML."
          }
        }
      }
    },
    "/categories/{category}.json": {
      "get": {
        "operationId": "getCategoryPlaces",
        "summary": "Catalogue des lieux d’une catégorie.",
        "parameters": [
          {
            "name": "category",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "immanquables",
                "plages",
                "points-de-vue",
                "restos",
                "marches",
                "bateau"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Données du guide en français.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "404": {
            "description": "Ressource absente. Le corps peut être HTML."
          }
        }
      }
    },
    "/places/{category}/{id}.json": {
      "get": {
        "operationId": "getPlace",
        "summary": "Lire une fiche complète avec ses sources.",
        "parameters": [
          {
            "name": "category",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "immanquables",
                "plages",
                "points-de-vue",
                "restos",
                "marches",
                "bateau"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifiant exact obtenu dans le catalogue.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Données du guide en français.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Detail"
                }
              }
            }
          },
          "404": {
            "description": "Ressource absente. Le corps peut être HTML."
          }
        }
      }
    },
    "/guides/{id}.json": {
      "get": {
        "operationId": "getGuide",
        "summary": "Lire une rubrique : conseils, marchés et événements, itinéraires, etc.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "index",
                "plages",
                "points-de-vue",
                "marches",
                "immanquables",
                "bateau",
                "restos",
                "conseils",
                "itineraires",
                "sources",
                "plus"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Données du guide en français.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Ressource absente. Le corps peut être HTML."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PlaceSummary": {
        "type": "object",
        "required": [
          "id",
          "category",
          "name",
          "api_url",
          "page_url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "api_url": {
            "type": "string"
          },
          "page_url": {
            "type": "string"
          }
        }
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "places": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlaceSummary"
            }
          }
        }
      },
      "Detail": {
        "type": "object",
        "required": [
          "id",
          "category",
          "name",
          "content_text",
          "data",
          "page_url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "content_text": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "page_url": {
            "type": "string"
          },
          "data_date": {
            "type": "string"
          },
          "freshness_note": {
            "type": "string"
          }
        }
      }
    }
  }
}