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.

VersionBase URLÉtat
v2https://api.arch-platform.com/api/v2la seule surface publique
v1https://api.arch-platform.com/api/v1retiré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 :

  1. 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.totalItems est le total de l'ensemble filtré, pas la taille de la page.
  2. L'identité d'une application change : /applications/{applicationId} prend un UUID stable, non plus le code métier. Le code reste exposé comme attribut — il peut changer, l'URL non. Un intégrateur qui migre doit mapper code → UUID.
  3. Les collections v2 refusent une limit hors 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.

MethodPathScopeRemplace
GET/business-functionsread/functions/flat, /functions/search, /functions/by-application/{code}
GET/business-functions/{functionId}read/functions/{id}
GET/business-functions/treeread/functions, et /functions/posi via ?include=applications
GET/business-functions/statisticsread/functions/stats

API v2 — Applications

MethodPathScope
GET/applicationsread
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

MethodPathScope
GET/tenant/invitationsread
POST/tenant/invitationswrite
GET/tenant/invitations/{invitationId}read
POST/tenant/invitations/{invitationId}/revokewrite

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

MethodPathScope
GET/tenant/membersread
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.

  1. L'identifiant change. La v1 adresse un membre par son sub OIDC — un identifiant interne, qui couple votre intégration à notre annuaire d'identités. La v2 utilise un memberId (UUID) stable, qu'il faut lire dans GET /tenant/members. Il n'existe pas de correspondance publique sub → memberId.
  2. 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, roles est 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

MethodPathScope
GET/diagrams/{diagramId}/revisionsread
POST/diagrams/{diagramId}/restorewrite

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.

  1. 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.totalItems dit combien il en reste réellement.
  2. 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 ».
  3. 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/applicationsGET /applications
GET /referentiel/applications/{code}GET /applications/{applicationId} — ⚠️ UUID, plus le code
GET /referentiel/functionsGET /business-functions/tree
GET /referentiel/functions/posiGET /business-functions/tree?include=applications
GET /referentiel/functions/flatGET /business-functions
GET /referentiel/functions/searchGET /business-functions?q=
GET /referentiel/functions/by-application/{code}GET /business-functions?applicationCode=
GET /referentiel/functions/statsGET /business-functions/statistics
GET /referentiel/functions/{id}GET /business-functions/{functionId}

Et pour le provisionnement d'utilisateurs :

Ancien chemin v1Équivalent v2
POST /tenant/invitationsPOST /tenant/invitations — inchangé, répond 201 + Location
GET /tenant/invitationsGET /tenant/invitations — enveloppé et paginé
DELETE /tenant/invitations/{id}POST /tenant/invitations/{invitationId}/revoke
GET /tenant/invitations/membersGET /tenant/members
PATCH /tenant/invitations/members/{userSub}/rolePATCH /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"
}

Voir Exemples ou Explorer pour tester en ligne.

On this page