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 la Référence API.

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": "about:blank",
  "title": "ambiguous_company",
  "status": 400,
  "code": "ambiguous_company",
  "detail": "cette clé couvre plusieurs sociétés (7, 12) — précisez l'en-tête X-Company-ID"
}

Le champ à tester dans votre code est code : il est stable, et la référence l’énumère route par route. detail s’adresse à qui débogue — il peut être reformulé. Les refus du domaine portent un code en capitales (MISSING_DURATION, EFFECTIVE_FROM_IN_FUTURE…), ceux du transport un code en minuscules (invalid_id, forbidden_resource, insufficient_scope…).

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 next_cursor ; repassez-le tel quel dans le paramètre cursor pour la page suivante. limit contrôle la taille de page : 50 par défaut, 200 au plus.

# 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=NTA" \
  -H "x-api-key: VOTRE_CLE_API"

Quand next_cursor vaut null, vous êtes à la fin. Le curseur est opaque : ne le fabriquez pas et n’en déduisez rien, contentez-vous de le renvoyer.

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.