API REST — Vue d'ensemble

L’API REST /v1 expose vos données Akuasense en JSON. Cette page décrit les conventions communes à tous les endpoints. Pour le détail de chaque endpoint, voir l’API Reference (en anglais).

URL de base & versionnement

https://api.hub.akuasense.com/v1

Le segment /v1 est la version majeure. Les ajouts rétrocompatibles se font dans /v1 ; un changement cassant donnerait /v2. Voir Versionnement.

Authentification

Clé API dans l’en-tête x-api-key. Multi-société via X-Company-ID. Détails et scopes : Authentification.

Format des dates et unités

• Dates / heures : ISO 8601 en UTC (ex. 2026-06-14T09:30:00Z).
• Mesures : chaque valeur numérique est accompagnée de son unit (jamais d’unité implicite). Les référentiels (cultures, textures…) sont renvoyés en { code, label }, le label étant localisable via le paramètre lang (défaut en).

Erreurs (RFC 9457)

Les erreurs suivent le standard Problem Details (RFC 9457) : un corps JSON application/problem+json.

{
  "type": "https://api.hub.akuasense.com/problems/ambiguous-company",
  "title": "Ambiguous company",
  "status": 400,
  "detail": "Your key covers several companies; set the X-Company-ID header.",
  "instance": "/v1/modules"
}

Statut	Signification courante
400	Requête invalide (ex. ambiguous_company)
401	Clé absente ou invalide
403	Scope ou rôle insuffisant
404	Ressource introuvable (ou hors de votre société)
409	Conflit (ex. idempotence)
429	Quota dépassé

Pagination par curseur

Les listes sont paginées par curseur (pas par numéro de page). La réponse contient un nextCursor ; passez-le dans le paramètre cursor pour la page suivante. limit contrôle la taille de page.

# Première page
curl "https://api.hub.akuasense.com/v1/modules?limit=50" \
  -H "x-api-key: VOTRE_CLE_API"

# Page suivante
curl "https://api.hub.akuasense.com/v1/modules?limit=50&cursor=eyJpZCI6..." \
  -H "x-api-key: VOTRE_CLE_API"

Quand nextCursor vaut null, vous êtes à la fin.

Quotas

Limite	Valeur
Par minute	60 requêtes
Par jour	10 000 requêtes

Au-delà, l’API renvoie 429. Espacez vos appels et mettez en cache les référentiels.

Information

Les écritures (POST/PUT/PATCH) acceptent un en-tête Idempotency-Key : réémettre la même requête avec la même clé ne crée pas de doublon. Recommandé pour les automatisations.

Idempotence des écritures

Fournissez un Idempotency-Key unique par opération logique. En cas de renvoi (réseau, réessai), l’API reconnaît la clé et renvoie le résultat initial au lieu de dupliquer.