API publique Hectarea et ressources pour agents

Hectarea expose une API REST publique, en lecture seule et sans authentification, qui décrit les projets agricoles français financés par la communauté. C’est la même API qui alimente les pages publiques du site.

Base URL et format

https://api.hectarea.io

Toutes les réponses sont enveloppées : { "success": true, "data": ... }. En cas d’erreur, la réponse porte { "success": false, "errorMessage": "...", "errorCode": 400 }. Le contenu est en français.

Endpoints publics

GET /v1/public/stories — Tous les projets agricoles publiés (cartes).
GET /v1/public/stories/slugs — Les slugs seuls, pour construire un index.
GET /v1/public/stories/meta — Régions et filières disponibles, avec le nombre de projets.
GET /v1/public/stories/{slug} — Détail complet d’un projet agricole.
GET /v1/public/stories/by-region/{region} — Projets d’une région.
GET /v1/public/stories/by-theme/{theme} — Projets d’une filière.
GET /v1/public/featured/finalized — Ordre éditorial des projets déjà financés.

Spécification machine : /openapi.json (OpenAPI 3.1).

Exemple

curl -s https://api.hectarea.io/v1/public/stories/meta | jq '.data.regions'

Négociation de contenu Markdown

Toutes les pages publiques d’app.hectarea.io répondent en Markdown quand un client le demande, conformément au profil acceptmarkdown.com.

curl -s -H "Accept: text/markdown" https://app.hectarea.io/club/investir/

Accept: text/markdown renvoie Content-Type: text/markdown; charset=utf-8
Toutes les pages négociées portent Vary: Accept, Accept-Encoding
Les q-values sont respectées : text/html;q=0.9, text/markdown;q=1.0 renvoie du Markdown.
Un Accept qui n’accepte ni HTML ni Markdown reçoit un 406.
Un chemin inexistant renvoie un vrai 404, avec un corps Markdown listant où chercher.

Fichiers lisibles par une machine

llms.txt — Résumé du site pour les modèles de langage, et quand faire appel à Hectarea.
agents.md — Instructions d'usage destinées aux agents : cas d'usage, appels, limites.
openapi.json — Spécification OpenAPI 3.1 de l’API publique en lecture seule.
Ressources développeurs — Documentation de l'API publique Hectarea et des fichiers machine.
sitemap.xml — Toutes les URL publiques indexables.

Limites d’usage

Volume et cache

L’API publique est destinée à un usage raisonnable en lecture. Identifiez votre agent par un User-Agent explicite et mettez les réponses en cache : les projets changent au plus quelques fois par jour. Pour un volume important ou un usage commercial, écrivez à contact@hectarea.io.

Ce qui n’est pas ouvert

Les endpoints qui ne commencent pas par /v1/public/ exigent un compte authentifié et ne sont pas ouverts aux intégrations tierces. Aucune donnée de membre, de portefeuille ou de souscription n’est accessible sans authentification. Il n’existe pas, à ce jour, de webhooks publics ni de serveur MCP officiel Hectarea.

Pages liées

Cette page est disponible en Markdown pour les agents : envoyez l’en-tête Accept: text/markdown sur cette même URL. Voir aussi les ressources développeurs.