Référence de l’API

Tout ce que fait l’application passe par une API JSON, que vous pouvez utiliser avec la clé de votre organisation. La référence complète et interactive se trouve sur /api/docs, générée à partir de /openapi.json.

La hiérarchie du registre que suivent les chemins de l’API : organisation, exploitation, serre, ligne, cycle de culture. — Les chemins du registre suivent la hiérarchie, de l’organisation jusqu’au cycle de culture.

Authentification

curl -H "X-API-Key: dl_…" https://your-deepleaf-address/api/organizations/org-1
curl -H "Authorization: Bearer dl_…" https://your-deepleaf-address/api/organizations/org-1

Une clé absente, inconnue ou révoquée reçoit 401. Un chemin relevant d’une autre organisation renvoie 404. Une clé membre reçoit 403 sur la gestion des clés et les paiements de facturation ; voir Organisation et clés. Utilisez l’adresse sur laquelle vous ouvrez l’application.

Notation abrégée des chemins

Ci-dessous, {cycle} désigne le chemin complet du cycle de culture :

/api/organizations/{organization_id}/farms/{farm_id}/greenhouses/{greenhouse_id}/rows/{row_id}/cycles/{cycle_id}

Les semaines s’écrivent 2026-W40, ou sous la forme de n’importe quelle date de cette semaine, YYYY-MM-DD.

Analyse

Méthode et chemin	Rôle
`POST /api/observations`	Envoie une photo ou une vidéo (champ multipart `file`, avec en option `mode`, `conf`, `sample_seconds`, `max_frames`, `mm_per_pixel`). Renvoie un identifiant de tâche.
`GET /api/observations/{id}`	L’état, l’avancement et le résultat, avec les images, les fruits, les tiges, les plants et `quality`.
`GET /api/observations/{id}/frames/{frame}/{name}`	Une image ou sa superposition.
`POST /api/examples/{key}`	Analyse l’une des photos d’exemple.
`POST {cycle}/videos`	Envoie un passage et l’enregistre dans un cycle et une semaine (`week`).
`POST {cycle}/videos/batch`	Jusqu’à 12 séquences vidéo, en champs `files` répétés, dans l’ordre du passage, analysées et comptées comme un seul passage. Le champ `clips` de la tâche indique l’avancement de chaque séquence.

Registre

Méthode et chemin	Rôle
`GET /api/organizations/{org}`	L’arborescence des exploitations, serres, lignes et cycles de l’organisation.
`POST …/farms`, `…/greenhouses`, `…/rows`, `…/cycles`	Crée un niveau.
`PATCH` sur le chemin d’un niveau	Modifie les noms et les détails. Les identifiants ne changent pas.
`GET` sur le chemin d’un niveau `+ /contents`	Le nombre d’éléments rattachés au niveau.
`DELETE` sur le chemin d’un niveau	409, avec les comptes, tant qu’il contient des éléments. `?cascade=true` le supprime avec son contenu.

Relevés

Méthode et chemin	Rôle
`POST / GET {cycle}/harvests`	Saisit une récolte (`week`, `kg`, `note`) ou les liste. `?week=` filtre.
`POST {cycle}/harvests/csv`	Envoie un fichier `week,kg[,note]`.
`PATCH / DELETE {cycle}/harvests/{id}`	Modifie ou supprime une récolte.
`POST / GET {cycle}/irrigation`	Saisit une entrée, ou les liste de la plus récente à la plus ancienne.
`PATCH / DELETE {cycle}/irrigation/{id}`	Modifie ou supprime une entrée.
`POST / GET {cycle}/climate`	Ajoute des relevés sous la forme `{"points": [...]}`, ou les liste (`metric`, `from`, `to`, `limit`, `offset`).
`POST {cycle}/climate/csv/preview`	Vérifie un fichier climatique sans l’enregistrer : la disposition détectée, la mesure, l’unité, la conversion et le degré de confiance de chaque colonne, le fuseau horaire et la période couverte, les premières lignes, les avertissements (`warnings`) et les problèmes bloquants (`problems`), ainsi qu’une correspondance (`mapping`) à confirmer. Accepte les mêmes champs de formulaire que l’envoi, dont `compartment` et `date_order` (`dmy` ou `mdy`).
`POST {cycle}/climate/csv`	Envoie un fichier climatique. Transmettez le `mapping` de l’aperçu pour importer exactement ce qui a été prévisualisé (les colonnes qui n’y figurent pas ne sont pas importées), ou `columns` pour les nommer vous-même. Refusé avec 400 tant que le fichier présente des problèmes, et avec 413 au-delà de la taille maximale.
`POST {cycle}/climate/file/preview`	Vérifie un export d’ordinateur climatique (CSV, texte ou `.xlsx`) sans l’enregistrer : le fichier, l’horloge de lecture (`time_zone`), chaque colonne avec sa mesure et son unité, les consignes, les premières heures, ce qui est déjà enregistré, les `warnings`, les `problems` bloquants et un `mapping` à confirmer.
`POST {cycle}/climate/file`	Enregistre les heures de l’export avec le `mapping` confirmé ; `remember` mémorise les choix de colonnes pour la serre. Les heures réimportées sont mises à jour, jamais doublées.
`POST {cycle}/climate/ingest`	Le même import pour un script à vous : le fichier comme corps de la requête, une clé dans un en-tête uniquement, les choix de colonnes enregistrés pour la serre. Voir Importer les données de votre ordinateur climatique.
`GET / DELETE {greenhouse}/climate/file-mapping`	Les choix de colonnes enregistrés pour une serre, ou leur oubli.
`GET {cycle}/climate/imports`	Les imports climatiques récents du cycle, du plus récent au plus ancien.
`POST {cycle}/climate/imports/{id}/undo`	Annule un import : supprime les relevés ajoutés et rétablit les valeurs modifiées. `409` si un import plus récent a modifié les mêmes relevés, sauf avec `{"confirm": true}`.
`PATCH / DELETE {cycle}/climate/{id}`	Modifie ou supprime un relevé.
`POST {cycle}/fruit-mass`	Poids saisis en grammes pour `green_g`, `turning_g`, `red_g`.
`POST {cycle}/weather`	Actualise immédiatement la météo extérieure à l’emplacement de la serre (`past_days`, `forecast_days`).

Semaines et prévisions

Méthode et chemin	Rôle
`GET {cycle}/weeks/{week}`	Le bilan de la semaine : comptages du passage, récolte, irrigation, climat, productivité de l’eau et prévision.
`GET {cycle}/forecast?week=`	La prévision pour la semaine du passage et les sept suivantes (par défaut : la semaine du dernier passage).
`POST / GET {cycle}/forecasts`	Émet et enregistre la prévision actuelle, ou liste les prévisions enregistrées avec la récolte constatée depuis.
`GET {cycle}/backtest`	L’erreur rejouée par horizon, comparée aux récoltes.
`GET {cycle}/export.csv`	Une ligne par semaine.

Corrections des passages

Ci-dessous, {walk} remplace /api/organizations/{org}/walks/{walk_id}, où walk_id est l’identifiant de tâche du passage. Voir Corriger un passage.

Méthode et chemin	Rôle
`GET {walk}/corrections`	Les corrections du passage, ses fruits après correction, les semaines de cycle de culture où il est enregistré, et les totaux `model` et `corrected`.
`POST {walk}/corrections`	En ajoute une. `kind` vaut `ripeness` (`track_id`, `ripeness`), `remove` (`track_id`), `add` (`ripeness`, `frame_id`, `box` sous la forme `[x1, y1, x2, y2]` en pixels) ou `counts` (`counts` avec `green`, `turning` ou `red`). Chacune accepte une `note` facultative.
`PATCH {walk}/corrections/{correction_id}`	Change la maturité, le cadre, les totaux ou la note. Le type et le fruit restent les mêmes.
`DELETE {walk}/corrections/{correction_id}`	Annule une correction.

Chaque réponse contient les totaux model et corrected du passage. Toute clé de l’organisation peut corriger, administrateur ou membre. Un passage d’une autre organisation répond 404, et un passage encore en cours d’analyse 409. Une deuxième correction sur le même fruit, un deuxième jeu de totaux ou plus de 2 000 corrections sur un passage reçoivent 409. Les totaux sont des nombres entiers de 0 à 1 000 000, et une note fait au plus 500 caractères.

Session et état

Méthode et chemin	Rôle
`GET /api/health`	Indique si l’analyse et la base de données sont disponibles. Aucune clé n’est nécessaire.
`GET / POST / DELETE /api/session`	Lit la session (avec le rôle de la clé, `role`), connecte (pose le cookie) ou déconnecte.
`GET / POST /api/organizations/{org}/keys`	Liste ou crée des clés. Clés administrateur uniquement ; une nouvelle clé ne s’affiche qu’une fois.
`PATCH …/keys/{id}`, `POST …/keys/{id}/revoke`	Renomme ou révoque une clé. La dernière clé administrateur reçoit 409.