> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Objects

> 3D models used for AR tracking in captures and as content in courses.

A **HolosObject** is a 3D model that can be tracked during a capture session, placed in a Holos Learn course, or both. The platform maintains a library of \~3,600 CC0 (open-license) objects alongside org-private objects that admins upload themselves.

## Object types

| Type           | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| Platform (CC0) | Open-license objects shared across all orgs                  |
| Org-private    | Objects uploaded by a specific org, visible only to that org |

## Supported formats

Org admins can upload models in any of these formats:

| Format | Notes                                              |
| ------ | -------------------------------------------------- |
| GLB    | Primary format, no conversion needed               |
| USDZ   | Converted to GLB post-upload; USDZ retained for AR |
| OBJ    | Converted to GLB via Blender Lambda post-upload    |
| FBX    | Converted to GLB via Blender Lambda post-upload    |

All uploads automatically produce a GLB for web preview and a USDZ for AR tracking where not already provided.

## Making an object trackable

For an object to be tracked during a capture session, it needs a `.referenceobject` file — an Apple ML-trained descriptor of its geometry, generated from the USDZ mesh.

The platform handles this as a processing request. When an admin links a non-trackable object to a skill, a request is automatically filed. The Holos team processes it and uploads the resulting `.referenceobject` file.

## Key fields

| Field                    | Description                                      |
| ------------------------ | ------------------------------------------------ |
| `name`                   | Display name                                     |
| `tags`                   | Searchable labels                                |
| `source.glb`             | S3 key for the GLB mesh                          |
| `source.usdz`            | S3 key for the USDZ mesh                         |
| `source.referenceObject` | S3 key for the `.referenceobject` AR descriptor  |
| `glbUrl`                 | Presigned download URL for GLB                   |
| `usdzUrl`                | Presigned download URL for USDZ                  |
| `referenceObjectUrl`     | Presigned download URL for `.referenceobject`    |
| `thumbnailUrl`           | Presigned URL for the thumbnail image            |
| `approvalStatus`         | `pending` · `approved` · `rejected`              |
| `conversionStatus`       | `pending` · `processing` · `complete` · `failed` |

## Endpoints

* `GET /api/org/:orgId/objects` — list objects (platform + org-private)
* `GET /api/org/:orgId/objects/by-ids/:ids` — batch fetch by `_id`
* `POST /api/org/:orgId/objects/upload` — initiate an org object upload
* `PATCH /api/org/:orgId/objects/:objectId` — update name, tags, approval status