{
  "openapi": "3.1.0",
  "info": {
    "title": "Hectarea Public API",
    "summary": "API publique en lecture seule des projets agricoles financés via Hectarea.",
    "description": "API REST publique d'Hectarea, la plateforme française de financement du foncier agricole. Elle expose, sans authentification, les projets agricoles publiés sur app.hectarea.io : ferme, agriculteur, filière, surface, territoire et avancement de la campagne de financement. C'est la même API qui alimente les pages publiques du site.\n\nToutes les réponses sont enveloppées dans `{ \"success\": boolean, \"data\": ... }`.\n\nLes endpoints qui ne commencent pas par `/v1/public/` exigent un compte authentifié et ne sont pas ouverts aux intégrations tierces.",
    "version": "1.0.0",
    "termsOfService": "https://www.hectarea.io/hectarea/mentions-legales",
    "contact": {
      "name": "Hectarea",
      "email": "contact@hectarea.io",
      "url": "https://app.hectarea.io/developpeurs/"
    },
    "x-brand": "Hectarea",
    "x-legal-name": "HECTAREA LA FONCIÈRE"
  },
  "externalDocs": {
    "description": "Documentation développeurs et agents Hectarea",
    "url": "https://app.hectarea.io/developpeurs/"
  },
  "servers": [
    {
      "url": "https://api.hectarea.io",
      "description": "API publique Hectarea"
    }
  ],
  "tags": [
    {
      "name": "projets",
      "description": "Projets agricoles publiés sur la plateforme."
    }
  ],
  "paths": {
    "/v1/public/stories": {
      "get": {
        "operationId": "listStories",
        "tags": ["projets"],
        "summary": "Lister tous les projets agricoles publiés",
        "description": "Renvoie la liste complète des projets agricoles publiés, ouverts au financement comme déjà financés.",
        "responses": {
          "200": {
            "description": "Liste des projets.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": { "$ref": "#/components/schemas/StoryCard" }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/stories/slugs": {
      "get": {
        "operationId": "listStorySlugs",
        "tags": ["projets"],
        "summary": "Lister les slugs des projets",
        "description": "Renvoie uniquement les identifiants d'URL des projets. Utile pour construire un index sans télécharger toutes les fiches. L'URL canonique d'un projet est `https://app.hectarea.io/club/terrain/{slug}/`.",
        "responses": {
          "200": {
            "description": "Liste de slugs.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": { "type": "array", "items": { "type": "string" } }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/stories/meta": {
      "get": {
        "operationId": "getStoriesMeta",
        "tags": ["projets"],
        "summary": "Lister les régions et filières disponibles",
        "description": "Renvoie les régions et les filières agricoles représentées sur la plateforme, avec le nombre de projets pour chacune. Les valeurs renvoyées sont celles à passer à `/v1/public/stories/by-region/{region}` et `/v1/public/stories/by-theme/{theme}`.",
        "responses": {
          "200": {
            "description": "Régions et filières.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": { "data": { "$ref": "#/components/schemas/StoriesMeta" } }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/stories/{slug}": {
      "get": {
        "operationId": "getStory",
        "tags": ["projets"],
        "summary": "Détail d'un projet agricole",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Identifiant d'URL du projet, tel que renvoyé par `/v1/public/stories/slugs`.",
            "schema": { "type": "string" },
            "example": "32-8-ha-en-elevage-de-brebis-texel-agneaux-labellises-marcillat-en-combraille"
          }
        ],
        "responses": {
          "200": {
            "description": "Fiche complète du projet.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": { "data": { "$ref": "#/components/schemas/StoryDetail" } }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Aucun projet publié pour ce slug.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
              }
            }
          }
        }
      }
    },
    "/v1/public/stories/by-region/{region}": {
      "get": {
        "operationId": "listStoriesByRegion",
        "tags": ["projets"],
        "summary": "Projets d'une région",
        "parameters": [
          {
            "name": "region",
            "in": "path",
            "required": true,
            "description": "Nom de région tel que renvoyé par `/v1/public/stories/meta`, encodé pour l'URL.",
            "schema": { "type": "string" },
            "example": "Nouvelle-Aquitaine"
          }
        ],
        "responses": {
          "200": {
            "description": "Projets de la région.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": { "$ref": "#/components/schemas/StoryCard" }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/stories/by-theme/{theme}": {
      "get": {
        "operationId": "listStoriesByTheme",
        "tags": ["projets"],
        "summary": "Projets d'une filière agricole",
        "parameters": [
          {
            "name": "theme",
            "in": "path",
            "required": true,
            "description": "Nom de filière tel que renvoyé par `/v1/public/stories/meta`, encodé pour l'URL.",
            "schema": { "type": "string" },
            "example": "Élevage"
          }
        ],
        "responses": {
          "200": {
            "description": "Projets de la filière.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": { "$ref": "#/components/schemas/StoryCard" }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/featured/finalized": {
      "get": {
        "operationId": "listFeaturedFinalized",
        "tags": ["projets"],
        "summary": "Ordre éditorial des projets déjà financés",
        "description": "Renvoie les projets financés dans l'ordre choisi par l'équipe éditoriale. Utilisé par le site pour ordonner la section « projets financés ».",
        "responses": {
          "200": {
            "description": "Projets financés, ordonnés.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": { "$ref": "#/components/schemas/StoryCard" }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Envelope": {
        "type": "object",
        "description": "Enveloppe commune à toutes les réponses /v1.",
        "required": ["success"],
        "properties": {
          "success": { "type": "boolean", "const": true }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": ["success"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "errorMessage": { "type": "string" },
          "errorCode": { "type": "integer" }
        }
      },
      "LandStatus": {
        "type": "string",
        "description": "Statut de la campagne de financement.",
        "enum": ["TEASING", "SALE", "SOLD_OUT"],
        "x-enum-descriptions": {
          "TEASING": "Projet annoncé, financement pas encore ouvert.",
          "SALE": "Campagne de financement ouverte.",
          "SOLD_OUT": "Projet intégralement financé."
        }
      },
      "StoryCard": {
        "type": "object",
        "description": "Projet agricole, version carte (listings).",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string", "description": "Titre du projet." },
          "slug": {
            "type": "string",
            "description": "Identifiant d'URL. Page canonique : https://app.hectarea.io/club/terrain/{slug}/"
          },
          "coverImageUrl": { "type": "string", "format": "uri" },
          "landType": {
            "type": "string",
            "description": "Filière agricole (Élevage, Viticulture, Arboriculture, Maraîchage, Grandes cultures, Polyculture...)."
          },
          "city": { "type": "string" },
          "state": { "type": "string", "description": "Région française." },
          "totalSizeInHa": { "type": "number", "description": "Surface du foncier concerné, en hectares." },
          "totalPriceInEuros": { "type": "number", "description": "Montant total de la campagne, en euros." },
          "totalInvestedAmount": { "type": "number", "description": "Montant déjà financé, en euros." },
          "nbInvestors": { "type": "integer", "description": "Nombre de membres ayant soutenu le projet." },
          "status": { "$ref": "#/components/schemas/LandStatus" },
          "latitude": { "type": "number" },
          "longitude": { "type": "number" },
          "descriptionHeaderString": { "type": "string", "description": "Accroche du projet, en texte brut." },
          "tags": { "type": "array", "items": { "type": "string" } },
          "startTs": { "type": "string", "format": "date-time", "description": "Ouverture de la campagne." },
          "farmerName": { "type": "string", "description": "Agriculteur soutenu." },
          "fundingReason": { "type": "string", "description": "Objet du financement (installation, agrandissement...)." },
          "youtubeVideoId": { "type": "string" },
          "estimatedReturnRange": { "type": "string", "description": "Fourchette indicative communiquée pour l'opération." }
        }
      },
      "StoryDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/StoryCard" },
          {
            "type": "object",
            "properties": {
              "descriptionHeader": { "type": "string", "description": "Accroche, format riche." },
              "descriptionContent": { "type": "string", "description": "Récit du projet, HTML." },
              "imgUrls": { "type": "array", "items": { "type": "string", "format": "uri" } },
              "address": { "type": "string" },
              "nbFarmer": { "type": "integer", "description": "Nombre d'agriculteurs concernés." },
              "estimatedReturnRate": { "type": "number" },
              "estimatedRentRevenueRate": { "type": "number" },
              "seoTitle": { "type": "string" },
              "seoDescription": { "type": "string" }
            }
          }
        ]
      },
      "StoriesMeta": {
        "type": "object",
        "properties": {
          "regions": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Facet" }
          },
          "themes": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Facet" }
          }
        }
      },
      "Facet": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "count": { "type": "integer" }
        }
      }
    }
  }
}