Référence des endpoints
Tous les endpoints exposés à l'API publique v2, et la correspondance depuis la v1 retirée.
L'API publique est la v2.
| Version | Base URL | État |
|---|---|---|
| v2 | https://api.arch-platform.com/api/v2 | la seule surface publique |
https://api.arch-platform.com/api/v1 | retirée de l'API publique le 2026-10-09 |
La v1 n'est plus joignable avec un jeton d'API. Depuis le 2026-10-09,
ses endpoints répondent 404 à un jeton personnel ou partenaire.
Les endpoints existent toujours — ils servent l'interface web — mais ils ne font plus partie du contrat public. La raison : ils partageaient leurs méthodes, leurs chemins et leurs DTO avec l'interface, de sorte que toute évolution de l'UI devenait une rupture de contrat public, et l'inverse. La v2 a ses propres représentations et peut évoluer séparément.
La correspondance complète v1 → v2 est dans le changelog.
Un endpoint absent retourne 404 avec un PAT — l'API admin n'est volontairement pas exposée.
La v2 n'est pas une simple renumérotation. Trois changements qui demandent une adaptation, pas un remplacement de préfixe :
- Les collections sont paginées et enveloppées. Une réponse de liste
est
{ items, page: { limit, nextCursor, previousCursor, totalItems } }, plus un tableau JSON nu.page.totalItemsest le total de l'ensemble filtré, pas la taille de la page. - L'identité d'une application change :
/applications/{applicationId}prend un UUID stable, non plus le code métier. Lecodereste exposé comme attribut — il peut changer, l'URL non. Un intégrateur qui migre doit mapper code → UUID. - Les collections v2 refusent une
limithors bornes (1 à 200) au lieu de la rogner en silence. Une page plus petite que demandée, sans le dire, fait croire à une fin de collection.
Les valeurs de filtre invalides étaient listées ici comme une
différence v1/v2. Elles n'en sont plus une : depuis le 2026-10-09, la v1
les refuse aussi en 400 (voir le changelog). Les deux versions se
comportent désormais pareil, et c'est volontaire — un filtre
silencieusement abandonné rendait 200 avec tout, et il n'y avait
aucune raison de laisser ce piège en place le temps d'une migration.
API v2 — Fonctions métier
Sept opérations v1 ramenées à quatre. /search et /by-application/{code}
deviennent des paramètres de requête, qui se combinent — ce que trois
chemins exclusifs ne permettaient pas.
| Method | Path | Scope | Remplace |
|---|---|---|---|
GET | /business-functions | read | /functions/flat, /functions/search, /functions/by-application/{code} |
GET | /business-functions/{functionId} | read | /functions/{id} |
GET | /business-functions/tree | read | /functions, et /functions/posi via ?include=applications |
GET | /business-functions/statistics | read | /functions/stats |
API v2 — Applications
| Method | Path | Scope |
|---|---|---|
GET | /applications | read |
GET | /applications/{applicationId} | read |
Le détail groupe les 52 champs plats de la v1 en sept sous-objets :
hosting, lifecycle, compliance, assessment, costs, contacts,
sync. La liste, elle, rend un résumé de onze champs — sans donnée de
conformité, de coût ni de contact.
API v2 — Invitations
| Method | Path | Scope |
|---|---|---|
GET | /tenant/invitations | read |
POST | /tenant/invitations | write |
GET | /tenant/invitations/{invitationId} | read |
POST | /tenant/invitations/{invitationId}/revoke | write |
La création répond 201 avec un en-tête Location désignant l'invitation.
La révocation est un POST …/revoke et non un DELETE : elle est une
transition d'état — la ligne survit avec le statut REVOKED — et la
réponse rend l'invitation dans son nouvel état.
API v2 — Membres
| Method | Path | Scope |
|---|---|---|
GET | /tenant/members | read |
GET | /tenant/members/{memberId} | read |
PATCH | /tenant/members/{memberId} | write |
DELETE | /tenant/members/{memberId} | write |
Les membres ont leur propre racine : en v1 ils vivaient sous
/api/v1/tenant/invitations/members, alors qu'ils ne sont pas des
invitations.
Deux ruptures sur les membres.
- L'identifiant change. La v1 adresse un membre par son
subOIDC — un identifiant interne, qui couple votre intégration à notre annuaire d'identités. La v2 utilise unmemberId(UUID) stable, qu'il faut lire dansGET /tenant/members. Il n'existe pas de correspondance publiquesub→memberId. - Un membre n'apparaît plus qu'une fois. La v1 rendait une ligne par
rôle accordé : une personne cumulant deux rôles y figurait deux fois.
En v2,
rolesest un tableau.
Le PATCH attend application/merge-patch+json et remplace les rôles du
membre par celui demandé — il ne les ajoute pas. Le DELETE répond 204 : le
membre quitte la collection et son GET répond ensuite 404.
API v2 — Diagrammes
| Method | Path | Scope |
|---|---|---|
GET | /diagrams/{diagramId}/revisions | read |
POST | /diagrams/{diagramId}/restore | write |
L'historique d'un diagramme d'architecture, et le retour en arrière. Une
révision par sauvegarde ; empty marque celle où le diagramme a été vidé,
qui est souvent celle qu'on veut défaire.
Trois choses à savoir.
- L'historique est borné. Seules les dernières révisions sont
conservées ; au-delà, les plus anciennes disparaissent à mesure que de
nouvelles arrivent.
page.totalItemsdit combien il en reste réellement. - La liste ne transporte pas les diagrammes. Un diagramme pèse jusqu'à 100 Ko : une page de 50 en ferait 5 Mo, pour un écran qui n'affiche que « version, quand, par qui ».
- Restaurer crée une version de plus, et ne réécrit jamais l'existant :
l'état d'avant la restauration reste donc lui-même restaurable. La
réponse donne la version atteinte — c'est elle qu'il faut envoyer comme
expectedVersionà la sauvegarde suivante.
Un diagramme est adressé par son diagramId (UUID), lisible dans la réponse
du diagramme lui-même.
API v1 — retirée de l'API publique
Ces neuf chemins étaient publics jusqu'au 2026-10-09. Avec un jeton d'API, ils
répondent désormais 404. Leur équivalent v2 est donné en regard.
| Ancien chemin v1 | Équivalent v2 |
|---|---|
GET /referentiel/applications | GET /applications |
GET /referentiel/applications/{code} | GET /applications/{applicationId} — ⚠️ UUID, plus le code |
GET /referentiel/functions | GET /business-functions/tree |
GET /referentiel/functions/posi | GET /business-functions/tree?include=applications |
GET /referentiel/functions/flat | GET /business-functions |
GET /referentiel/functions/search | GET /business-functions?q= |
GET /referentiel/functions/by-application/{code} | GET /business-functions?applicationCode= |
GET /referentiel/functions/stats | GET /business-functions/statistics |
GET /referentiel/functions/{id} | GET /business-functions/{functionId} |
Et pour le provisionnement d'utilisateurs :
| Ancien chemin v1 | Équivalent v2 |
|---|---|
POST /tenant/invitations | POST /tenant/invitations — inchangé, répond 201 + Location |
GET /tenant/invitations | GET /tenant/invitations — enveloppé et paginé |
DELETE /tenant/invitations/{id} | POST /tenant/invitations/{invitationId}/revoke |
GET /tenant/invitations/members | GET /tenant/members |
PATCH /tenant/invitations/members/{userSub}/role | PATCH /tenant/members/{memberId} |
DELETE /tenant/invitations/members/{userSub} | DELETE /tenant/members/{memberId} |
Voir le guide Provisioning utilisateurs pour le workflow d'invitation.
Format des erreurs (RFC 9457)
{
"type": "https://arch-platform.com/errors/invalid-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "Token scope 'read' insufficient for POST /applications",
"instance": "/api/v2/applications"
}