What contextId Accepts

contextId is a required path parameter on every /v1/twin/{contextId}/... and /v1/reality-plan/{contextId}/... route. It is polymorphic: several different id types resolve through it, which is why a well-formed UUID can still come back 404. This page covers what each route family accepts and the exact errors you’ll see when it doesn’t.

---

What contextId identifies

Route family	contextId accepts
/v1/twin/{contextId}/... (space, assets, POIs, zones, drafts, business objects, embed sessions)	A twin id, the id of the site the twin belongs to, or the id of one of the twin’s drafts
/v1/reality-plan/{contextId}/... (space, layouts, bundles, model assets)	A RealityPlan Project id, or the id of one of its layouts

The two families are mutually exclusive: a twin route only ever resolves a twin-shaped id, and a RealityPlan route only ever resolves a project-shaped id.

A valid id of the wrong kind: 404, not 400

Passing a well-formed id that belongs to the other family doesn’t fail validation: it resolves to a real context, just not one this route serves. The API responds 404 Not Found with a message naming what the route does serve:

{
  "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"
}

Some routes append a hint pointing at the counterpart route that does serve the other kind. For example, GET /v1/twin/{contextId}/space appends:

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.

and GET /v1/reality-plan/{contextId}/space appends the mirror image:

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.

Not every route has a counterpart. Assets, POIs, zones, drafts, and business object search exist for twins only, and model assets and layouts exist for RealityPlan Projects only; those routes carry no hint, just the base message for what they serve.

Note

The wrong-kind response is a 404, never a 400: the id itself is valid, it just isn’t addressable on that route. Treat it the same way you’d treat any other “not found on this route.”

A non-UUID contextId: 400

If contextId isn’t a UUID at all, the API rejects it before it ever reaches a route handler:

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

This check happens ahead of standard request validation, so it’s the message you’ll see for a malformed contextId regardless of which route family you’re calling.

Finding the right id

Walk down from GET /oauth/api-info through GET /v1/nodes/{id}/browse to find a twin, site, draft, project, or layout id: see Finding Your IDs for the full walkthrough. Once you have an id, this page tells you which route families it unlocks.