Library API

Use the public Palatial Asset Library to display existing assets in your application, download an archive for a simulator, or create an independent asset in a workspace. These routes cover the public Library; Organization Library entries and private email-link assets use separate access flows.

Examples use https://dashboard.palatial.cloud. Replace YOUR_API_KEY, SOURCE_ASSET_ID, and the example workspace and copy IDs with your own values. Contact Palatial for a sandbox or staging environment. This page describes the API contract for integrations; see the Isaac Sim plugin guide for the features available in the released plugin.

Authentication and workspace access

Create a workspace API key as described in Using the API, then send either x-api-key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY.

Operation	Required key capability	Required workspace access
Download a public Library asset	`asset:export`	Current edit access to the key’s workspace
Copy into a workspace	`asset:create`	Current edit access to the destination, within the key’s scope
Read copy progress	`asset:read`	Current read access to the copied asset’s workspace, within the key’s scope

The source Library asset may belong to another workspace. A workspace key can only create a copy in its own workspace and poll copies in that workspace. A legacy unscoped user key still needs current authorization for the explicitly requested destination. These routes do not grant access to private source assets or expand the scope of ordinary workspace asset routes.

Downloads and copies require a source that is published in the public Library, READY, and neither deleted nor withdrawn. These endpoints accept user API keys; internal-service keys are rejected. Disabled, revoked, or expired keys are also rejected. The capabilities above are existing capabilities; no additional Library capability is needed.

Browse assets and display previews

Use the existing public routes under /api/v1/library/ to populate a Library browser. They do not require a dashboard session or API key.

Operation	Method and path
Browse or search assets	`GET /api/v1/library/search`
List categories	`GET /api/v1/library/categories`
List collections	`GET /api/v1/library/collections`
Browse a collection	`GET /api/v1/library/collections/{collectionId}/assets`
Resolve thumbnail URLs	`POST /api/v1/library/thumbnails` with `{ "ids": ["ASSET_ID"] }`
Check available download formats	`GET /api/v1/library/assets/{assetId}/export-engines`

Search accepts q, limit, and cursor. Omit page to use cursor pagination, then pass the returned nextCursor as cursor for the next request while keeping the search and filters unchanged. Collection asset lists use the same pagination pattern.

curl -G "https://dashboard.palatial.cloud/api/v1/library/search" \
  --data-urlencode "q=chair" \
  --data-urlencode "limit=20" \
  --data-urlencode "includeValidationPlayback=true"

curl -X POST "https://dashboard.palatial.cloud/api/v1/library/thumbnails" \
  -H "Content-Type: application/json" \
  -d '{"ids":["SOURCE_ASSET_ID"]}'

The thumbnail response maps each requested ID to { "downloadUrl": "..." } or null. Use these URLs for images; a storage key such as uploads/... is not an image URL. Request includeValidationPlayback=true on search or collection lists for optional video previews. Handle absent thumbnails or videos without blocking selection or downloads.

Use the export-engines endpoint before presenting download choices. Its export_engines lists available simulator archives; download_packages can contain "usd" for an original USD package. A simulator compatibility filter does not guarantee an archive for that simulator.

Download a Library asset

GET /api/v1/external/library/assets/{sourceAssetId}/download

Parameter	Required	Meaning
`sourceAssetId` (path)	Yes	The public Library asset ID, a 24-character hexadecimal ID
`engine` (query)	No	One of `isaac_sim`, `mujoco`, or `newton`

Omit engine for an original USD package. Supplying an engine for that package returns 400. For generated assets, omitting engine uses the asset’s existing export selection; pass an engine to request a particular available simulator archive.

curl "https://dashboard.palatial.cloud/api/v1/external/library/assets/SOURCE_ASSET_ID/download?engine=isaac_sim" \
  -H "x-api-key: YOUR_API_KEY"

Successful response (200):

{
  "url": "https://download.example/short-lived-download",
  "fileName": "Chair-IsaacSim.zip",
  "source": "worker"
}

This endpoint returns JSON containing an archive URL. Fetch the returned url promptly, save it using fileName, then extract and import the archive in your application. The URL expires; request a fresh one if needed. Keep your API key on the Palatial API request and do not forward it to the returned download URL. source identifies the download transport and can vary.

Existing export eligibility and any first-export credit gate still apply. A successful download request does not create a workspace asset. Use the copy endpoint below if you also need the asset in a workspace.

Copy into a workspace

POST /api/v1/external/library/assets/{sourceAssetId}/copy

Field	Required	Meaning
`sourceAssetId` (path)	Yes	The public Library asset ID
`workspace` (JSON body)	Yes	Destination workspace ID, a 24-character hexadecimal ID

For a workspace key, workspace must match that key’s workspace. The new asset’s owner is resolved from the API key. Do not send owner, a source ID in the body, or other additional fields.

curl -X POST "https://dashboard.palatial.cloud/api/v1/external/library/assets/SOURCE_ASSET_ID/copy" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace":"6a1877e186e965169202aa03"}'

Successful response (201, example while the copy is running):

{
  "id": "6a1877e186e965169202aa02",
  "workspace": "6a1877e186e965169202aa03",
  "status": { "status": "INIT" },
  "libraryClone": {
    "phase": "r2_copying",
    "r2ObjectsCopied": 0,
    "r2TotalObjects": 3,
    "r2Errors": 0
  }
}

The request creates a new private asset and starts an asynchronous copy of its files. Editing the copy does not change the Library source. Save the returned id: it identifies the new workspace asset and is the ID used for polling. A 201 response does not mean the copy is ready to use.

A pending copy immediately reserves capacity under the destination organization’s configured asset cap, if one is set. Concurrent copies across that organization’s workspaces share the cap. Failed or deleted pending copies release their reservations. Reaching the cap returns 400.

Check copy progress

GET /api/v1/external/library/copies/{newAssetId}/status

Use the new asset ID returned by the copy request, with a key authorized for the destination workspace.

curl "https://dashboard.palatial.cloud/api/v1/external/library/copies/6a1877e186e965169202aa02/status" \
  -H "x-api-key: YOUR_API_KEY"

Successful response (200, completed example):

{
  "phase": "complete",
  "r2ObjectsCopied": 3,
  "r2TotalObjects": 3,
  "r2Errors": 0,
  "projectStatus": "READY"
}

Field	Meaning
`phase`	Copy state, described below
`r2ObjectsCopied`	Number of storage objects copied
`r2TotalObjects`	Expected storage object count, when known
`r2Errors`	Reported storage copy errors
`errorMessage`	Failure detail, when present
`projectStatus`	Status of the new workspace asset

Poll read-only status requests every few seconds with bounded backoff and an overall timeout.

State	Client action
`r2_queued`, `r2_copying`, `r2_recovering`, or `db_cloning`	Keep waiting within the polling timeout; files or asset metadata are still being copied
`phase: "complete"` and `projectStatus: "READY"`	The new asset is ready to use
`phase: "failed"`	Stop and show `errorMessage`, if present
`projectStatus: "DELETED"`, or the asset becomes missing or inaccessible	Stop polling; the copy is no longer available to this caller
`phase: "idle"`	This ID has no Library copy state; verify that you saved the copy response’s new asset ID

Treat complete without READY as not ready. If it does not become ready within your timeout, retain the asset ID and last response for support; do not start a duplicate copy automatically. Storage object counts alone do not establish readiness.

After completion, use the ordinary workspace asset routes, such as GET /api/v1/external/assets/{newAssetId} and its media and export routes, with the destination workspace key.

Errors

HTTP status	Meaning
`400`	Invalid ID, engine, or destination; additional request fields; unavailable source files for copying; or the organization asset cap was reached
`403`	Invalid or disabled key, missing capability, insufficient workspace access, private source, or an existing export credit gate
`404`	Library source missing, deleted, or withdrawn; or the requested archive is unavailable
`409`	Source not ready, temporary copy admission contention, or another conflicting service state
`500` or `503`	A service failure; retry read-only checks with backoff, and inspect the workspace before repeating a copy whose outcome is unknown

Workspace access is checked on every authenticated request. A key for another workspace cannot poll the new copy. If the key owner’s edit access is removed, new downloads and copies are rejected; copy status remains readable only while current read access is retained.