Introduction to Data Bundles

A data bundle is the container for one capture: raw input files (point clouds, trajectories, images, and so on) plus the processed outputs the platform generates from them. The RealityConnect API exposes the same bundle lifecycle the Prevu3D UI uses, so integrations can create bundles, upload data, launch processing, track progress, and retrieve input files without a browser.

This document assumes you have completed an OAuth flow and hold an access_token, your regional api_url, and your organization_id. See the flow guides if you do not.

All data bundle workflow endpoints (/v1/bundles/..., /v1/organization/.../data-bundle-input-tree, and /v1/nodes/.../bundle) are marked experimental. Expect the contract to evolve until they graduate to stable. See Experimental endpoints.

Required scopes

Scope	Used for
read:bundle	Fetch the device input tree, list upload sessions, list processing options, list processing records, list input file download URLs
write:bundle	Create a bundle, open and finalize upload sessions, start processing

You also need content access and node permissions on the parent node where the bundle is created, and on the bundle itself for later steps.

End-to-end flow

flowchart LR
  A["1. Get input tree"] --> B["2. Create bundle"]
  B --> C["3. Upload input files"]
  C --> D["4. List processing options"]
  D --> E["5. Start processing"]
  E --> F["6. Poll processing records"]

Each numbered step maps to a dedicated guide:

Step	Guide	Summary
1–2	Creating a Data Bundle	Fetch the device input tree, pick a leaf dbuPath, create the bundle under a parent node
3	Uploading Data to a Data Bundle	Open an upload session, multipart-upload each file to S3, finalize
4–6	Processing and Monitoring	List available outputs, launch processing, poll until every job reaches a terminal state

Downloading Input Files is optional: use it only when you need to retrieve the bundle’s uploaded input files again.

Validation model

Structural rules (mandatory file types, allowed extensions, cross-type dependencies, multiplicity) are described in the requirements array returned when you open an upload session. It is the user’s responsibility to follow that structure before uploading and before launching processing.

The upload API records each file under the type you provide and completes the session on count alone. Deep content validation (whether a .las is a genuine device capture, whether metadata JSON correctly references its image) happens after launching a processing, not at upload time. A correctly named but malformed file uploads without error and fails later during processing.

Processing failures caused by an incorrect upload structure (missing mandatory types, broken dependencies, wrong extensions, and so on) will not be refunded.