Ce que contextId accepte

contextId est un paramètre de chemin obligatoire sur toutes les routes /v1/twin/{contextId}/... et /v1/reality-plan/{contextId}/.... Il est polymorphe : plusieurs types d’id différents s’y résolvent, ce qui explique pourquoi un UUID bien formé peut malgré tout renvoyer 404. Cette page décrit ce que chaque famille de routes accepte et les erreurs exactes que vous rencontrerez sinon.

---

Ce que contextId identifie

Famille de routes	contextId accepte
/v1/twin/{contextId}/... (space, assets, POI, zones, brouillons, objets métier, sessions d’intégration)	Un id de twin, l’id du site auquel appartient le twin, ou l’id d’un de ses brouillons
/v1/reality-plan/{contextId}/... (space, layouts, bundles, model assets)	Un id de RealityPlan Project, ou l’id d’un de ses layouts

Les deux familles s’excluent mutuellement : une route twin ne résout jamais qu’un id de type twin, et une route RealityPlan ne résout jamais qu’un id de type projet.

Un id valide du mauvais type : 404, pas 400

Un id bien formé appartenant à l’autre famille n’échoue pas à la validation : il se résout vers un contexte réel, simplement pas celui que cette route dessert. L’API répond 404 Not Found avec un message précisant ce que la route dessert réellement :

{
  "statusCode": 404,
  "message": "This route serves twins. It accepts a twin id, the id of the site it belongs to, or the id of one of its drafts.",
  "error": "Not Found"
}

{
  "statusCode": 404,
  "message": "This route serves design projects. It accepts a design project id or the id of one of its layouts.",
  "error": "Not Found"
}

Certaines routes ajoutent une indication pointant vers la route homologue qui dessert l’autre type. Par exemple, GET /v1/twin/{contextId}/space ajoute :

This route serves twins. It accepts a twin id, the id of the site it belongs to, or the id of one of its drafts. The composition of a design project or a layout is served by GET /v1/reality-plan/{contextId}/space.

et GET /v1/reality-plan/{contextId}/space ajoute le symétrique :

This route serves design projects. It accepts a design project id or the id of one of its layouts. The composition of a twin or a twin draft is served by GET /v1/twin/{contextId}/space.

Toutes les routes n’ont pas d’homologue. Les assets, POI, zones, brouillons et la recherche d’objets métier n’existent que pour les twins ; les model assets et les layouts n’existent que pour les RealityPlan Project ; ces routes ne portent aucune indication, seulement le message de base sur ce qu’elles desservent.

Note

La réponse pour le mauvais type est un 404, jamais un 400 : l’id lui-même est valide, il n’est simplement pas adressable sur cette route. Traitez-la comme n’importe quel autre « introuvable sur cette route ».

Un contextId qui n’est pas un UUID : 400

Si contextId n’est même pas un UUID, l’API le rejette avant même d’atteindre un gestionnaire de route :

{
  "statusCode": 400,
  "message": "Context ID must be a UUID",
  "error": "Bad Request"
}

Cette vérification a lieu avant la validation standard des requêtes : c’est donc le message que vous verrez pour un contextId mal formé, quelle que soit la famille de routes appelée.

Trouver le bon id

Descendez depuis GET /oauth/api-info via GET /v1/nodes/{id}/browse pour trouver un id de twin, de site, de brouillon, de projet ou de layout : consultez Finding Your IDs pour le parcours complet. Une fois l’id en main, cette page vous indique quelles familles de routes il débloque.