Referencia de la API

Todo lo que hace la aplicación pasa por una API JSON que puede usar con la clave de su organización. La referencia completa e interactiva está en /api/docs, generada a partir de /openapi.json.

La jerarquía del registro que siguen las rutas de la API: organización, finca, invernadero, hilera, ciclo de cultivo. — Las rutas del registro siguen la jerarquía, desde la organización hasta el ciclo de cultivo.

Autenticación

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

Una clave ausente, desconocida o revocada recibe 401. Una ruta de otra organización devuelve 404. Una clave de miembro recibe 403 en la gestión de claves y en los pagos de facturación; consulte Organización y claves. Use la dirección con la que abre la aplicación.

Abreviatura de rutas

Más abajo, {cycle} representa la ruta completa del ciclo de cultivo:

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

Las semanas se escriben 2026-W40 o como cualquier fecha de esa semana, YYYY-MM-DD.

Análisis

Método y ruta	Qué hace
`POST /api/observations`	Sube una foto o un vídeo (campo multipart `file`, con `mode`, `conf`, `sample_seconds`, `max_frames` y `mm_per_pixel` opcionales). Devuelve un identificador de tarea.
`GET /api/observations/{id}`	El estado, el avance y el resultado, con fotogramas, frutos, tallos, plantas y `quality`.
`GET /api/observations/{id}/frames/{frame}/{name}`	Una imagen de fotograma o su superposición.
`POST /api/examples/{key}`	Analiza una de las fotos de ejemplo.
`POST {cycle}/videos`	Sube un recorrido y lo guarda en un ciclo y una semana (`week`).
`POST {cycle}/videos/batch`	Hasta 12 clips de vídeo como campos `files` repetidos, en orden de recorrido, analizados y contabilizados como un solo recorrido. El campo `clips` de la tarea muestra el avance de cada clip.

Registro

Método y ruta	Qué hace
`GET /api/organizations/{org}`	El árbol de fincas, invernaderos, hileras y ciclos de la organización.
`POST …/farms`, `…/greenhouses`, `…/rows`, `…/cycles`	Crea un nivel.
`PATCH` en la ruta de un nivel	Cambia nombres y detalles. Los identificadores se mantienen.
`GET` en la ruta de un nivel `+ /contents`	Los conteos de todo lo que hay bajo el nivel.
`DELETE` en la ruta de un nivel	409, con los conteos, mientras contenga algo. `?cascade=true` lo elimina con su contenido.

Registros

Método y ruta	Qué hace
`POST / GET {cycle}/harvests`	Registra una cosecha (`week`, `kg`, `note`) o las enumera. `?week=` filtra.
`POST {cycle}/harvests/csv`	Sube un archivo `week,kg[,note]`.
`PATCH / DELETE {cycle}/harvests/{id}`	Edita o elimina una cosecha.
`POST / GET {cycle}/irrigation`	Registra una entrada, o las enumera de la más reciente a la más antigua.
`PATCH / DELETE {cycle}/irrigation/{id}`	Edita o elimina una entrada.
`POST / GET {cycle}/climate`	Añade lecturas como `{"points": [...]}`, o las enumera (`metric`, `from`, `to`, `limit`, `offset`).
`POST {cycle}/climate/csv/preview`	Comprueba un archivo de clima sin guardarlo: el formato detectado; la métrica, la unidad, la conversión y el grado de confianza de cada columna; la zona horaria y el periodo cubierto; las primeras filas; los avisos (`warnings`) y los problemas que bloquean la importación (`problems`), y una asignación (`mapping`) para confirmar. Acepta los mismos campos de formulario que la subida, incluidos `compartment` y `date_order` (`dmy` o `mdy`).
`POST {cycle}/climate/csv`	Sube un archivo de clima. Envíe el `mapping` de la vista previa para importar exactamente lo que se previsualizó (las columnas que no figuran en él no se importan), o `columns` para nombrarlas usted mismo. Se rechaza con 400 mientras el archivo tenga problemas, y con 413 por encima del tamaño máximo.
`POST {cycle}/climate/file/preview`	Comprueba una exportación del ordenador de clima (CSV, texto o `.xlsx`) sin guardarla: el archivo, el reloj con que se lee (`time_zone`), cada columna con su medida y unidad, las consignas, las primeras horas, lo ya guardado, los `warnings`, los `problems` que bloquean y un `mapping` para confirmar.
`POST {cycle}/climate/file`	Guarda las horas de la exportación con el `mapping` confirmado; `remember` guarda las opciones de columnas del invernadero. Las horas reimportadas se actualizan, nunca se duplican.
`POST {cycle}/climate/ingest`	La misma importación para un script propio: el archivo como cuerpo de la petición, una clave solo en un encabezado, las opciones de columnas guardadas del invernadero. Vea Importar los datos de su ordenador de clima.
`GET / DELETE {greenhouse}/climate/file-mapping`	Las opciones de columnas guardadas de un invernadero, u olvidarlas.
`GET {cycle}/climate/imports`	Las importaciones de clima recientes del ciclo, de la más nueva a la más antigua.
`POST {cycle}/climate/imports/{id}/undo`	Deshace una importación: quita las lecturas añadidas y recupera los valores cambiados. `409` si una importación posterior cambió las mismas lecturas, salvo con `{"confirm": true}`.
`PATCH / DELETE {cycle}/climate/{id}`	Edita o elimina una lectura.
`POST {cycle}/fruit-mass`	Gramos introducidos para `green_g`, `turning_g`, `red_g`.
`POST {cycle}/weather`	Actualiza al momento el clima exterior de la ubicación del invernadero (`past_days`, `forecast_days`).

Semanas y previsiones

Método y ruta	Qué hace
`GET {cycle}/weeks/{week}`	La lectura semanal: conteos del recorrido, cosecha, riego, clima, productividad del agua y previsión.
`GET {cycle}/forecast?week=`	La previsión para la semana del recorrido y las siete siguientes (por defecto, la semana del último recorrido).
`POST / GET {cycle}/forecasts`	Emite y guarda la previsión actual, o enumera las guardadas junto con la cosecha registrada desde entonces.
`GET {cycle}/backtest`	El error reproducido por horizonte, frente a las cosechas.
`GET {cycle}/export.csv`	Una fila por semana.

Correcciones de recorridos

A continuación, {walk} sustituye a /api/organizations/{org}/walks/{walk_id}, donde walk_id es el id de trabajo del recorrido. Consulte Corregir un recorrido.

Método y ruta	Qué hace
`GET {walk}/corrections`	Las correcciones del recorrido, sus frutos después de ellas, las semanas del ciclo de cultivo en que está guardado y los conteos `model` y `corrected`.
`POST {walk}/corrections`	Añade una. `kind` es `ripeness` (`track_id`, `ripeness`), `remove` (`track_id`), `add` (`ripeness`, `frame_id`, `box` como `[x1, y1, x2, y2]` en píxeles) o `counts` (`counts` con `green`, `turning` o `red`). Cada una admite una `note` opcional.
`PATCH {walk}/corrections/{correction_id}`	Cambia la maduración, el recuadro, los conteos o la nota. El tipo y el fruto no cambian.
`DELETE {walk}/corrections/{correction_id}`	Deshace una corrección.

Cada respuesta incluye los conteos model y corrected del recorrido. Cualquier clave de la organización puede corregir, de administrador o de miembro. Un recorrido de otra organización responde 404, y un recorrido que aún se analiza, 409. Una segunda corrección sobre el mismo fruto, un segundo juego de totales o más de 2000 correcciones en un recorrido reciben 409. Los conteos son números enteros de 0 a 1.000.000, y una nota tiene como máximo 500 caracteres.

Sesión y estado

Método y ruta	Qué hace
`GET /api/health`	Indica si el análisis y la base de datos están disponibles. No necesita clave.
`GET / POST / DELETE /api/session`	Lee la sesión (con la función de la clave, `role`), inicia sesión (fija la cookie) o la cierra.
`GET / POST /api/organizations/{org}/keys`	Enumera o crea claves. Solo claves de administrador; una clave nueva se muestra una sola vez.
`PATCH …/keys/{id}`, `POST …/keys/{id}/revoke`	Cambia el nombre de una clave o la revoca. La última clave de administrador recibe 409.