Node Thumbnails
A data node (division, site, folder, twin, and the rest of the hierarchy) can carry a thumbnail image. This page covers uploading, replacing, and removing that thumbnail, and the cost and lifetime of the signed URL you get back when you ask for it.
Uploading a thumbnail
Section titled “Uploading a thumbnail”| Method | Path | Description |
|---|---|---|
POST | /v1/nodes/{nodeId}/thumbnail | Initiate: returns an upload id and a presigned S3 URL |
POST | /v1/nodes/{nodeId}/thumbnail/{uploadId}/finalize | Finalize: applies the uploaded image as the node’s thumbnail |
DELETE | /v1/nodes/{nodeId}/thumbnail | Remove: deletes the current thumbnail |
All three require write:hierarchy and are marked experimental. See Experimental endpoints.
This is the same initiate/upload/finalize shape used by several other RealityConnect API upload endpoints. See the Shared Multipart Upload Reference for the full mechanic. Node thumbnails are that pattern’s simple, single-file case: initiate takes no request body and returns exactly one presigned URL, with no partNumber and no refresh endpoint. PUT the image to that URL, then call finalize to apply it. If the URL expires before you upload to it, re-initiate to get a fresh one, since there is nothing to refresh.
DELETE /v1/nodes/{nodeId}/thumbnail is idempotent: it returns 204 whether or not the node had a thumbnail.
Accepted formats and size limits
Section titled “Accepted formats and size limits”Initiate takes no body. Unlike some of the API’s other upload flows, you don’t declare a file name, size, or content type upfront. The API does not itself document or enforce an image format allow-list or a maximum file size; a file the downstream image processor can’t decode fails at finalize rather than at the PUT step. Treat any non-204 response from finalize as “this file didn’t work” and surface that to the caller, rather than assuming any image you can PUT will be accepted.
Getting a thumbnail back
Section titled “Getting a thumbnail back”GET /v1/nodes/{id}/browse and GET /v1/nodes/search both accept includeThumbnail=true (default false). When set, every node in the response gets a thumbnailSignedUrl field: null when the node has no thumbnail, a signed URL when it does. See Node Types and Hierarchy for the rest of the DataNode shape.
includeThumbnail defaults to false because it isn’t free: generating and signing a URL is extra work per node, done for every item on the page, not only the ones a caller actually renders. Asking for it on a browse or search call already near its page-size limit (20 for browse, 50 for search) means paying that cost for the whole page. Request it only on the view that renders images, not on a bulk listing or a background sync of the tree.
Signed URL lifetime
Section titled “Signed URL lifetime”thumbnailSignedUrl is a presigned link, and RCAPI does not publish or configure how long it stays valid, so treat it as short-lived and opaque, not as a durable identifier. Don’t cache a thumbnailSignedUrl past the response that returned it. If your integration caches browse or search results and re-renders them later, re-fetch with includeThumbnail=true to get a current URL rather than replaying a stored one: a stored URL will eventually stop resolving, serving a dead image link with no warning from the rest of the response.
Thumbnails and soft-delete
Section titled “Thumbnails and soft-delete”Soft-deleting a node (DELETE /v1/nodes/{nodeId}) moves it to the trash without touching its thumbnail. GET /v1/trash accepts the same includeThumbnail=true and returns the same thumbnailSignedUrl for a trashed node that browse and search would have returned before it was deleted. Restoring the node (PATCH /v1/nodes/{nodeId}/restore) makes it browsable and searchable again with the thumbnail intact; nothing needs to be re-uploaded. Hard-deleting the node (DELETE /v1/nodes/{nodeId}/hard), or letting the 30-day trash retention lapse, removes the thumbnail along with everything else on the node. See What Delete Actually Does, Per Resource for the full delete/restore/purge model.
What’s next?
Section titled “What’s next?”- Shared Multipart Upload Reference for the initiate/upload/finalize mechanic in full.
- Node Types and Hierarchy for the full
DataNodeshape and the browse/search field reference. - What Delete Actually Does, Per Resource for soft-delete, restore, and purge behavior across every resource.