Conventions de l'API
Format des requêtes et des erreurs, validation stricte, identifiants, pagination, filtres, idempotence, CORS, tailles, délais et évolution de l'API.
Ces règles valent pour tous les endpoints de l'API publique https://api.wakastart.app/api. Les pages de domaine ne signalent que ce qui s'en écarte.
Format des requêtes et des réponses
- Les corps de requête et de réponse sont en JSON, encodés en UTF-8. Envoyez
Content-Type: application/json. - Les envois de fichiers utilisent
multipart/form-data, avec le fichier dans le champfile. - Les dates sont au format ISO 8601, en UTC :
2026-10-23T09:12:44.512Z. - Les montants de paiement sont en centimes, dans des champs suffixés
Cents:unitAmountCents: 4900vaut 49,00.
Identifiants
La plupart des objets ont deux identifiants :
| Identifiant | Format | Exemple | Usage |
|---|---|---|---|
| UUID | 36 caractères | 3f9a6c2e-1b7d-4c55-9e0a-6b2f4d8a1c01 | Identifiant technique, attendu dans les champs nommés …Id |
| WID | 6 caractères alphanumériques | EXCLI1 | Identifiant court, attendu dans les champs et chemins nommés …Wid ou :wid |
Chaque paramètre indique lequel il attend. Quelques chemins acceptent l'un ou l'autre ; ils le signalent.
Validation des champs
L'API valide chaque corps de requête et chaque paramètre de requête contre la liste des champs déclarés :
- un champ inconnu est refusé, avec
400et le messageproperty <nom> should not exist; - un champ obligatoire absent, un type incorrect ou une contrainte non respectée donnent
400; - les paramètres de requête sont convertis vers le type attendu :
?limit=20est lu comme le nombre 20,?isActive=truecomme un booléen.
N'envoyez donc que les champs documentés. Un client qui recopie un objet lu par l'API pour le renvoyer tel quel en modification sera refusé : construisez le corps de la modification champ par champ.
Erreurs
Toute erreur est renvoyée avec un statut HTTP 4xx ou 5xx et ce corps :
{
"statusCode": 403,
"message": "Droit applicatif requis : users.read",
"error": "Forbidden",
"timestamp": "2026-10-23T09:12:44.512Z",
"path": "/api/config/users"
}| Champ | Type | Description |
|---|---|---|
statusCode | entier | Statut HTTP, identique à celui de la réponse |
message | chaîne ou tableau de chaînes | Cause de l'erreur. Pour une erreur de validation, un tableau avec un message par champ en défaut |
error | chaîne | Libellé générique de l'erreur. Indicatif : fondez votre traitement sur statusCode et message |
timestamp | chaîne ISO 8601 | Date de l'erreur |
path | chaîne | Chemin appelé, paramètres de requête compris |
Exemple d'erreur de validation :
{
"statusCode": 400,
"message": ["property nickname should not exist", "email must be an email"],
"error": "Bad Request",
"timestamp": "2026-10-23T09:12:44.512Z",
"path": "/api/config/users"
}Une erreur produite par un service interne de Wakastart vous est transmise avec son statut et son message d'origine. Une erreur inattendue donne 500 avec le message générique Internal server error, sans détail technique. Chaque statut est détaillé dans Codes d'erreur.
Pagination
Plusieurs formats de pagination coexistent selon le domaine. Chaque endpoint de liste indique le sien.
| Format | Paramètres | Réponse | Utilisé par |
|---|---|---|---|
| Page et taille | page (≥ 1, défaut 1), limit (1 à 100, défaut 20) | { "data": [...], "meta": { "page", "limit", "total", "totalPages" } } | Utilisateurs, clients, réseaux, équipes, profils, invitations |
| Page et taille, réponse à plat | page (défaut 1), limit (1 à 100, défaut 20) | { "data": [...], "total", "page", "limit", "totalPages" } | Journal d'audit |
| Page et taille par page | page (défaut 1), perPage (1 à 100, défaut 20) | { "items": [...], "total", "page", "perPage" } | Membres d'une organisation |
| Curseur | startingAfter (identifiant du dernier élément reçu), limit (1 à 100) | { "data": [...], "hasMore", "nextCursor" } | Factures et abonnements de l'utilisateur final |
| Aucune | — | Liste complète | Thèmes, langues et traductions d'une application, membres d'une équipe, droits d'un profil |
Pour parcourir une liste paginée par page, incrémentez page jusqu'à totalPages. Pour une liste à curseur, rappelez l'endpoint avec startingAfter égal à nextCursor tant que hasMore vaut true.
async function* allUsers(token: string) {
for (let page = 1; ; page++) {
const res = await fetch(`https://api.wakastart.app/api/config/users?page=${page}&limit=100`, {
headers: { Authorization: `Bearer ${token}` },
});
if (!res.ok) throw new Error(`API ${res.status}`);
const { data, meta } = await res.json();
yield* data;
if (page >= meta.totalPages) return;
}
}Filtres et tri
- Les listes de l'organisation acceptent des filtres de portée :
partnerWid,networkWid,customerWid(6 caractères au plus) ou leurs équivalents UUIDpartnerId,networkId,customerId. - Pour un appel par clé API, ces filtres sont remplacés par la portée de la clé : son client, sinon son réseau, sinon son application.
- Les filtres propres à chaque liste (
isActive,status,action…) sont décrits avec l'endpoint. - L'API n'expose aucun paramètre de tri.
Idempotence
- Les créations de paiement (sessions Checkout, achat de pack de crédits) exigent un champ
idempotencyKeydans le corps, de 180 caractères au plus. Rejouer la même clé ne crée pas de seconde session. Générez une clé par intention d'achat, par exemple un UUID stocké avec la commande. - Les endpoints du module HDS acceptent l'en-tête
Idempotency-KeysurPOST,PUTetPATCH: la réponse est rejouée pendant 24 heures, avec l'en-têteX-Idempotency-Replayed: true. - Ailleurs, l'API n'offre pas d'idempotence : rejouer une création peut produire un doublon ou une erreur
409(utilisateur ou invitation déjà existants). Avant de réessayer une création qui a échoué sur un délai dépassé, vérifiez par une lecture si l'objet existe.
Limites de débit
L'API limite le nombre de requêtes par adresse IP, sur trois fenêtres simultanées :
| Fenêtre | Limite |
|---|---|
| 1 seconde | 10 requêtes |
| 1 minute | 100 requêtes |
| 1 heure | 1 000 requêtes |
Exceptions :
| Endpoint | Limite |
|---|---|
GET /api/invitations/verify/{token}, POST /api/invitations/accept/{token} | 60 par seconde, 600 par minute, 5 000 par heure |
POST /api/token/enrich | Aucune limite |
Au-delà, l'API répond 429 avec le message ThrottlerException: Too Many Requests. La réponse porte un en-tête par fenêtre dépassée, Retry-After-short, Retry-After-medium ou Retry-After-long, qui indique le nombre de secondes à attendre ; un navigateur ne peut pas les lire en appel croisé. Attendez ce délai, ou à défaut réessayez avec un délai croissant (1 s, 2 s, 4 s…). Si plusieurs instances de votre service sortent par la même adresse IP, elles partagent ces compteurs. Discovery a ses propres limites, décrites dans Discovery. Toutes les valeurs sont regroupées dans Limites et quotas.
CORS et appels depuis un navigateur
L'API publique n'accepte les appels d'un navigateur que depuis les origines que Wakastart a déclarées pour elle. Les en-têtes acceptés en appel croisé sont Content-Type, Authorization et x-api-key ; x-enriched-token n'en fait pas partie.
Nous recommandons d'appeler l'API depuis le serveur de votre application, qui ajoute le jeton de l'utilisateur. Si votre front doit l'appeler directement, envoyez le jeton Keycloak dans Authorization et demandez à Wakastart d'autoriser l'origine de votre front.
Tailles maximales
| Contenu | Taille maximale |
|---|---|
| Corps JSON ou formulaire | 1 Mo |
| Fichier envoyé à l'antivirus | 100 Mo |
| Fichier envoyé au module HDS | 100 Mo |
| Fichier CSV d'import d'utilisateurs | 2 Mo et 500 lignes |
| Jeton passé dans un corps de requête | 10 000 caractères |
Un fichier qui dépasse la taille maximale est refusé avec 413.
Délais d'attente
L'API relaie chaque requête vers un service interne de Wakastart et attend sa réponse 5 à 10 secondes pour la plupart des endpoints, 60 secondes pour le module HDS et 120 secondes pour l'envoi d'un fichier à l'antivirus ou la traduction par IA. Fixez le délai de votre client HTTP au-dessus de ces valeurs.
Évolution de l'API
L'API publique n'a pas de numéro de version, ni dans l'URL, ni dans un en-tête. Les évolutions sont publiées dans les notes de version. Pour que votre intégration résiste aux ajouts :
- ignorez les champs de réponse que vous ne connaissez pas ;
- n'attendez pas un ordre précis des éléments d'une liste ;
- traitez une valeur d'énumération inconnue comme un cas par défaut.
État de l'API
/api/healthzPublic. Indique que l'API répond.
curl -s https://api.wakastart.app/api/healthz{
"status": "ok",
"timestamp": "2026-10-23T09:12:44.512Z",
"uptime": 86400,
"service": "ws-back-api",
"version": "1.0.0"
}