Conventions
Pagination, tri, identifiants et formats communs à toutes les routes.
Les routes de l'API third-party partagent quelques conventions. Elles sont décrites ici une fois plutôt que répétées sur chaque page.
Base et format
Toutes les routes vivent sous /api/v1/external. Les requêtes et réponses sont
en JSON (Content-Type: application/json), sauf l'envoi de fichiers, en
multipart/form-data.
Les corps de requête sont validés strictement : une propriété inconnue est
refusée (400), pas ignorée. Les types sont convertis quand c'est sans
ambiguïté — "true" en booléen, "10" en nombre dans une query string.
Pagination
Les routes de liste acceptent les mêmes paramètres de requête :
| Paramètre | Type | Défaut | Rôle |
|---|---|---|---|
page | nombre ≥ 1 | 1 | Page demandée |
pageSize | nombre ≥ 1 | 10 | Éléments par page |
sortBy | chaîne | — | Champ de tri ; sans lui, tri sur l'identifiant (ordre de création) |
sortDirection | ASC | DESC | DESC | Sens du tri |
disablePagination | booléen | false | Renvoie tout, sans découpage |
La réponse enveloppe les éléments et décrit la pagination :
{
"data": [ … ],
"meta": {
"currentPage": 1,
"itemsPerPage": 10,
"totalItemsCount": 42,
"totalPagesCount": 5
}
}totalItemsCount compte l'ensemble, pas la page. Pour tout parcourir,
itérez sur page jusqu'à totalPagesCount, ou passez disablePagination=true
sur les listes que vous savez courtes.
disablePagination=true renvoie tous les éléments en une réponse. Sur une
liste de fichiers ou de sessions, elle peut être longue : réservez-le aux
listes bornées (organisations, clés).
Identifiants
Les identifiants (organizationId, agentId, keyId…) sont des chaînes
opaques. Ne les construisez pas, ne les interprétez pas : ils viennent toujours
d'une réponse précédente ou du claim organizations du jeton.
Dates
Les dates sont des chaînes ISO 8601 en UTC (2026-09-14T10:32:00.000Z), en
lecture comme en écriture. Les bornes de période (startDate, endDate de la
consommation) suivent le même format.
Recherche et filtres
Les listes qui acceptent search filtrent sur le texte, sans sensibilité à la
casse. Les autres filtres (status, category, scope…) prennent une valeur
parmi une liste fermée, documentée sur la page de la route.