Using the API

Use the Palatial API to use the Isaac Sim plugin or create SimReady 3D assets from images, text, or CAD files, track generation progress, and download results programmatically. All routes below use your API key and live under:

https://dashboard.palatial.cloud/api/v1/external/

Contact Palatial if you need a sandbox or staging environment for integration testing.

---

Creating an API key

API keys are created per workspace. A key can only read and generate assets inside the workspace it was created in, and only workspace members (or organization admins) can create one. See Roles and permissions.

1. Open the workspace in the dashboard and select the API tab next to Assets, Exports, and Team.

   

2. Click New key. Give the key a name so you can recognise it later (for example the pipeline or machine that will use it). The expiration date and rate limits are optional.

   

3. Click Create API Key. The key is shown once. Copy it and store it in your secret manager now; after you close this dialog it cannot be displayed again.

   

4. Click I’ve saved my key. The key now appears in the list with a masked value, its scope, and when it was last used. Revoke removes it immediately; requests using a revoked key return 403.

   

Send the key on every request using one of:

• Header: x-api-key: YOUR_API_KEY
• Header: Authorization: Bearer YOUR_API_KEY
• Query: ?api_key=YOUR_API_KEY

Never paste a key into a chat message, screenshot, public issue, or source file. If a key may have been exposed, revoke it from the API tab and create a new one.

Typical flow

1. Create an asset with one of the generation endpoints (Image → Sim, Text → Sim, or CAD → Sim).
2. Poll status until the asset is READY (or handle PROCESSING_FAILED).
3. Download the SimReady export ZIP or individual outputs (mesh, texture, collisions, etc.).

Feature highlights

• Generated textures support 2K, 4K, and 8K requests. The confirmation card and API response show the settings used for each asset.
• Texture optimization can reduce oversized maps without upscaling smaller maps.
• Geometry reduction supports automatic quality selection and an optional explicit target for integrations that need tighter output-size control.
• Asset Variants: branch a successful asset into a new independent asset by describing the desired change in feedback.

---

Authentication & access

Key type	What you can access
Workspace API key (recommended)	Assets and workspaces tied to that workspace
User-scoped key	Assets you own in your workspaces
Master key (enterprise)	Broader access; some calls require an explicit owner field

If you receive 403 Forbidden, check that the asset belongs to the workspace attached to your API key and that you have the required workspace access and any applicable generation balance.

---

HTTP status codes

Code	Meaning
200	Success
201	Resource created
307	Redirect (export download , follow with -L in cURL)
400	Invalid request (check field names and values)
403	Invalid API key or insufficient permissions/credits
404	Asset or workspace not found
409	Request conflicts with the current resource state
500	Server error , retry with backoff
503	Service temporarily unavailable , retry with backoff

---

Asset lifecycle

When you create or submit an asset, status.status moves through states like:

Status	Meaning
INIT	Created but not yet submitted (Text → Sim may start here briefly)
SUBMITTED	Queued for processing
QUEUED	Accepted, waiting to start
PROCESSING_IMPORT	Generation in progress
PROCESSING_PAUSED	Paused mid-pipeline (uncommon for API flows)
READY	Done , outputs are available to download
PROCESSING_FAILED	Failed , check status.displayText on the asset
PROCESSING_CANCELED	Canceled

Poll GET …/status every few seconds until you see READY or a terminal failure state. The status object may also include progress, completedSteps, totalSteps, and displayText for a coarse progress indicator.

---

Typical workflow (Image → Sim)

# 1a. Create and submit - If using a Single Image
curl -X POST "https://dashboard.palatial.cloud/api/v1/external/assets/create/imagetosim" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "name=Storage Bin" \
  -F "description=A rigid plastic storage bin with a hinged lid"

# 1b. Create and submit - If using Multiview
curl -X POST "https://dashboard.palatial.cloud/api/v1/external/assets/create/imagetosim" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "front=@chair_front.jpg" \
  -F "left=@chair_left.jpg" \
  -F "back=@chair_back.jpg" \
  -F "right=@chair_right.jpg" \
  -F "name=Office Chair" \
  -F "description=Black mesh office chair with armrests" \
  -F "shape_model=auto"

# Response includes "id" ,  save it as ASSET_ID

# 2. Poll until READY
curl "https://dashboard.palatial.cloud/api/v1/external/assets/ASSET_ID/status" \
  -H "x-api-key: YOUR_API_KEY"

# 3. Download SimReady export
curl -L -o export.zip \
  "https://dashboard.palatial.cloud/api/v1/external/assets/ASSET_ID/media/export" \
  -H "x-api-key: YOUR_API_KEY"

---

Assets

Base path: /api/v1/external/assets

---

List assets

GET /api/v1/external/assets

Returns a paginated list of assets in your workspace. Query: pass a filter object (JSON) with optional fields:

Field	Description
where.workspace	Filter by workspace ID
where.search	Search by name
where.status.status	Filter by status (e.g. READY)
limit	Page size (default 10)
skip	Offset for pagination
sort	{ “createdAt”: -1 } or { “updatedAt”: -1 }

curl -G "https://dashboard.palatial.cloud/api/v1/external/assets" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'filter={"limit":20,"sort":{"updatedAt":-1}}'

---

Get asset

GET /api/v1/external/assets/{id}

Returns the full asset record: name, type, parameters, status, export info, and metadata.

---

Create asset (JSON)

POST /api/v1/external/assets

Creates a draft asset without starting generation. You must call Submit separately. Required: name, workspace Optional: description, parameters, pipeline options (mesh_density, shape_model, texture_model, engine, etc.)

---

Update asset

PATCH /api/v1/external/assets/{id}

Update name, description, parameters, or other metadata on an existing asset.

---

Submit asset

POST /api/v1/external/assets/{id}/submit

Starts or restarts processing for an existing asset. Body (optional JSON):

Field	Description
type	Pipeline type, e.g. imagetosimready, cadtosimready
retry	Retry reason string (stored on the asset)

---

Reprocess from a pipeline stage

POST /api/v1/external/assets/{id}/reprocess

Re-runs an existing asset starting from a specific pipeline stage. This keeps the same asset ID and asset type, writes reprocess controls onto the asset, and submits it for processing again. Use this when you want to regenerate one step, such as shape or texture, without creating a brand-new asset. Body (JSON):

Field	Required	Description
from	Yes	Stage key to re-run from, e.g. shape-generation, parts-gen, texture, physics, validation-playback
mode	No	step stops after the requested stage; auto runs downstream stages automatically. Defaults to step.
stopAfter	No	Explicit stage to stop after. Defaults to from when mode is step.
sourceRunId	No	Exact prior product run whose artifacts should seed this reprocess.
destination	No	overwrite updates the current asset in place; variant creates a product variant run on the same asset. Defaults to overwrite.
feedback	No	Optional instruction for the regenerated stage. Max 4,000 characters.

Example , regenerate texture only and pause:

curl -X POST "https://dashboard.palatial.cloud/api/v1/external/assets/ASSET_ID/reprocess" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "texture", "mode": "step" }'

Example , regenerate from shape and continue downstream:

curl -X POST "https://dashboard.palatial.cloud/api/v1/external/assets/ASSET_ID/reprocess" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "from": "shape-generation", "mode": "auto" }'

Response: 200 OK , returns the queued reprocess/run response for the asset. After calling this endpoint, poll GET /api/v1/external/assets/{id}/status or GET /api/v1/external/assets/{id}/pipeline-runs/current until the asset reaches READY, PROCESSING_PAUSED, PROCESSING_FAILED, or PROCESSING_CANCELED.

Errors:

• 400 , invalid stage key, invalid mode, missing asset workspace, or invalid reprocess request.
• 403 , the API key does not have submit access to the asset, or the workspace has insufficient credits/limits.
• 404 , asset not found.

---

Get asset status

GET /api/v1/external/assets/{id}/status

Returns the current processing status. Use this to poll during generation. Response fields: status, progress, completedSteps, totalSteps, displayText, timestamps.

---

Cancel asset processing

DELETE /api/v1/external/assets/{id}/cancel-processing

Stops queued, active, or paused processing and moves the asset to PROCESSING_CANCELED. Cancellation is accepted while the asset is SUBMITTED, QUEUED, PROCESSING_IMPORT, PROCESSING_EDIT, MESH_GENERATED, TEXTURE_GENERATED, or PROCESSING_PAUSED. Repeating the request for an already canceled asset is safe.

curl -X DELETE \
  "https://dashboard.palatial.cloud/api/v1/external/assets/ASSET_ID/cancel-processing" \
  -H "x-api-key: YOUR_API_KEY"

Response , 200 OK:

{ "success": true }

After a successful request, poll GET /api/v1/external/assets/{id}/status until it returns PROCESSING_CANCELED. Errors:

• 400 , the asset is not currently processing.
• 403 , the API key does not have access to the asset.

---

Batch get statuses

POST /api/v1/external/assets/statuses

Body: { “ids”: [“id1”, “id2”] } Returns status and export for each ID , useful when tracking many assets.

---

Detailed progress (optional)

GET /api/v1/external/assets/{id}/pipeline-runs/current

Returns per-stage progress for the current generation run (stages[], currentStageKey, overall run status). Use this if you need stage-level detail beyond the coarse /status response.

---

Generation

One-shot endpoints that create and submit an asset in a single call.

Articulation modes

What you want	Parameters
Single solid object	enable_parts_segmentation: false, no articulation flags
Rigid parts (no joints)	enable_parts_segmentation: true
Articulated parts (doors, wheels, etc.)	create_articulation: true (or agentic_articulation: true)

Target simulator

Set engine to one of: isaac_sim, mujoco, or newton. Default: Isaac Sim.

---

Image → Sim

POST /api/v1/external/assets/create/imagetosim

Content-Type: multipart/form-data Create a SimReady asset from one photo, or from multiple photos of the same object for multi-view reconstruction.

Images

Send either a single file or named view fields for multiview , not both.

Field	Required	Description
file	One of file / view fields	Single input image (PNG, JPG, JPEG).
front	One of file / view fields	Front-facing photo of the object (PNG, JPG, JPEG).
left	One of file / view fields	Left-side photo (PNG, JPG, JPEG).
back	One of file / view fields	Back-facing photo (PNG, JPG, JPEG).
right	One of file / view fields	Right-side photo (PNG, JPG, JPEG).

Multiview rules:

• Provide at least 2 of front, left, back, right.
• All four is recommended for best reconstruction quality.
• Omit any view you do not have.
• Each view is a separate form field , the field name is the view label.

Parameters

Field	Required	Default	Description
name	Yes	,	Asset name (4–50 characters)
description	Yes	,	Object description / prompt (max 500 chars)
workspace	No	API key workspace	Workspace ID
engine	No	[isaac_sim]	Array of simulation engines: isaac_sim, mujoco, or newton. Omit this multipart field for the default single-engine request; send repeated engine fields when requesting multiple engines.
mesh_quality	No	high	low, medium, high
collision_quality	No	sdf	low, medium, high, x_high, sdf
shape_model	No	auto	auto,  parametric
texture_model	No	auto	auto
decimation	No	Legacy adaptive behavior when omitted	Omit this field or pass true for adaptive reduction with triangle_count=auto; pass false to explicitly disable decimation.
decimation_mode	No	auto	auto for quality-driven adaptive decimation, or strict with exactly one explicit target.
decimation_target_faces	Strict only	,	Maximum face-count target from 4 to 10,000,000. Mutually exclusive with decimation_target_ratio.
decimation_target_ratio	Strict only	,	Fraction of source faces to retain from 0.001 to 0.999. Mutually exclusive with decimation_target_faces.
texture_size	No	4096	Requested texture size: 2048 (2K), 4096 (4K), or 8192 (8K).
optimize_textures	No	true	Downscale oversized generated texture maps without upscaling smaller maps.
texture_max_resolution	No	4096	Maximum texture long edge: 512, 1024, 2048, 4096, or 8192. Smaller maps are never upscaled.
create_articulation	No	false	true for articulated parts
enable_parts_segmentation	No	true	false for a single rigid mesh; true for segmented static parts
reconstruct	No	true when 2+ views	Enable multiview mesh reconstruction
triangle_count	No	auto	minimal, low, medium, high, x_high, auto
mesh_density	No	medium	low, medium, high (when triangle_count is auto)
run_simulation	No	true	Run physics validation

Image → Sim optimization example:

curl -X POST "https://dashboard.palatial.cloud/api/v1/external/assets/create/imagetosim" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "name=Optimized Trolley" \
  -F "description=Static trolley prepared for realtime simulation" \
  -F "enable_parts_segmentation=false" \
  -F "decimation_mode=strict" \
  -F "decimation_target_ratio=0.04" \
  -F "texture_size=2048" \
  -F "optimize_textures=true" \
  -F "texture_max_resolution=2048"

Use decimation_target_faces instead of decimation_target_ratio when you need an absolute maximum face count. Do not send both targets. Response: 201 Created , asset is submitted and processing begins. Save the returned id.

---

Text → Sim

POST /api/v1/external/assets/create/texttosim

Content-Type: application/json Same options as Image → Sim, but send a JSON body with name and description only , no image file. Palatial generates a reference image, then starts the pipeline. The asset may briefly show INIT before moving to SUBMITTED. Poll /status until READY.

---

CAD → Sim

POST /api/v1/external/assets/create/cadtosim

Content-Type: multipart/form-data Files:

Field	Required	Formats
mesh	Yes	STEP, IGES, OBJ, GLB, FBX, STL, USD, JT, and others
image	Yes	PNG, JPG, JPEG (preview/reference photo)
datasheet	No	PDF

Common parameters: mostly the same as Image → Sim, plus CAD-only fields below. Not used on CAD: mesh_quality, shape_model.

Field	Required	Default	Description
enable_parts_segmentation	No	false	Run AI part segmentation on the uploaded CAD mesh. Set true for rigid parts without joints.
create_articulation	No	false	true for articulated parts (also forces part segmentation on)
apply_textures	No	true	Generate textures from the reference image
decimation	No	false	Backward-compatible switch. Prefer decimation_mode for new integrations.
decimation_mode	No	,	auto for quality-driven adaptive decimation, or strict with exactly one explicit target.
decimation_target_faces	Strict only	,	Maximum face-count target from 4 to 10,000,000. Mutually exclusive with decimation_target_ratio.
decimation_target_ratio	Strict only	,	Fraction of source faces to retain from 0.001 to 0.999. For example, 0.25 retains about 25%. Mutually exclusive with decimation_target_faces.
texture_size	No	4096	Requested texture size: 2048 (2K), 4096 (4K), or 8192 (8K).
optimize_textures	No	true	Downscale oversized generated texture maps without upscaling smaller maps.
texture_max_resolution	No	4096	Maximum texture long edge: 512, 1024, 2048, 4096, or 8192. Smaller maps are never upscaled.
units	No	m	Source units: m, cm, mm, inch, feet
up_direction	No	y	Source up axis: x, y, z
triangle_count	No	auto	Legacy preset selector. With decimation=true, auto maps to adaptive mode and fixed presets map to strict face targets.
mesh_density	No	medium	Only when triangle_count is auto

Advanced geometry and texture controls are optional. Use automatic settings unless your integration requires a specific output-size or texture-size target.

Strict face-target example:

curl -X POST "https://dashboard.palatial.cloud/api/v1/external/assets/create/cadtosim" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "name=Optimized Factory Scene" \
  -F "description=Factory scene prepared for realtime simulation" \
  -F "decimation_mode=strict" \
  -F "decimation_target_faces=50000" \
  -F "texture_size=4096" \
  -F "optimize_textures=true" \
  -F "texture_max_resolution=4096"

Strict retained-ratio example:

curl -X POST "https://dashboard.palatial.cloud/api/v1/external/assets/create/cadtosim" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "name=Quarter Density Factory Scene" \
  -F "description=Retain about one quarter of the source faces" \
  -F "decimation_mode=strict" \
  -F "decimation_target_ratio=0.25"

---

Create a Variant

POST /api/v1/external/assets/{id}/variants

Content-Type: application/json Create and submit a new independent asset from a successful source asset. The request body requires only feedback. Palatial interprets the requested difference and chooses the required regeneration work automatically. This endpoint requires a workspace API key with asset:variant-create.

Field	Required	Default	Description
feedback	Yes	,	Plain-language description of what should differ from the source asset (max 2,000 characters).
name	No	Generated from the request	Name for the new asset (4–50 characters).
description	No	Source asset description	Description for the new asset (max 500 characters).
parameters	No	Source asset settings	Applicable generation settings to override. Explicit values take precedence over settings inferred from feedback.

Only the fields above are accepted; do not send undocumented control fields. Example:

curl -X POST "https://dashboard.palatial.cloud/api/v1/external/assets/ASSET_ID/variants" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback": "Make the mug matte blue rubber while preserving its form."
  }'

Allow time for the create request to complete before treating it as failed. Each POST is a separate create request; do not automatically repeat a request whose outcome is unknown after a connection timeout. Response: 201 Created, returns the new asset. Save its id, then use the existing status, cancellation, and download endpoints. The example below shows selected response fields.

{
  "id": "NEW_ASSET_ID",
  "name": "Blue Rubber Mug",
  "description": "A simulation-ready mug",
  "type": "imagetosimready",
  "status": { "status": "SUBMITTED" },
  "requestedChange": {
    "instruction": "Apply a matte blue rubber finish while preserving the form.",
    "changeClasses": ["appearance"],
    "referenceImage": {
      "mimeType": "image/jpeg"
    }
  }
}

requestedChange reports how the request was interpreted. Reference-image metadata may be included when the requested change requires one; it is omitted when the change does not use an image. Behavior and limits:

• The source asset is never overwritten. The returned id belongs to a new asset in the same Variant family.
• Feedback can describe appearance, geometry, parts, collision, physics, articulation, or validation changes. Palatial chooses the required work; clients do not choose a pipeline stage.
• Requests that cannot produce a real difference are rejected before creation and charging.
• CAD geometry cannot be changed through feedback. Upload the modified CAD file as a new asset instead.
• A visible change to a multiview source may be rejected when one generated reference image cannot safely replace the complete view set. Common failures:

HTTP status	When it occurs
400	Missing or blank feedback, invalid values, or fields that are not part of the public contract.
403	Missing capability, invalid key, insufficient credits, or Variant creation is unavailable.
404	The source asset was not found or is outside the key workspace.
409	The source is not ready, or the requested change is unsupported or ineffective.
503	The request cannot be interpreted or prepared safely at this time. An explicit 503 response creates and charges nothing.

---

Generate image preview

POST /api/v1/external/assets/generate-image

Body: { “prompt”: “…”, “articulationType”: “single_object” } Returns a preview image as base64 without creating an asset. Useful for testing prompts before a full generation run.

---

Download outputs

All paths are under /api/v1/external/assets/{id}/…. Requires x-api-key.

Method	Path	What you get
GET	/media/export	SimReady export ZIP. Returns redirect , use curl -L.
GET	/media/mesh	Shape / mesh GLB
GET	/media/texture	Textured mesh GLB (?final_viewer=true optional)
GET	/media/collisions	Collision meshes
GET	/media/parts	Segmented parts GLB
GET	/media/articulated_meshes	Articulated mesh GLB
GET	/media/validation-report	Physics validation JSON
GET	/media/image	Source / preview image
POST	/media/images	Batch thumbnails , body { “ids”: [“…”] }
POST	/media/upload-url	Presigned URL to upload a mesh for editing workflows

Download intermediate outputs before READY

GET /api/v1/external/assets/{id}/process-file/{process}

Check whether a pipeline stage output is ready and get a download URL.

process value	Output
shape-generation	Base mesh
texture	Textured mesh
collision-preview	Collision geometry
articulation	Articulated mesh
physics-predictions	Physics data
validation-playback	Validation artifacts

Response:

Field	Meaning
state: “pending”	Not ready yet , poll again
state: “found”	Ready , use files[].downloadUrl
state: “skipped”	Stage not applicable for this asset
state: “error”	Stage failed , see reason

---

Workspaces

Base path: /api/v1/external/workspaces

Method	Path	Description
GET	/workspaces	List your workspaces
GET	/workspaces/{id}	Get workspace details (credits, plan, etc.)
GET	/workspaces/{id}/members	List workspace members

---

Users

Base path: /api/v1/external/users

Method	Path	Description
GET	/users	Your user profile
GET	/users/{id}	Profile for your user ID

---

Scenes

Organize assets into scenes within a workspace.

Method	Path	Description
GET	/workspaces/{workspaceId}/scenes	List scenes
POST	/workspaces/{workspaceId}/scenes	Create scene
GET	/scenes/{sceneId}	Get scene
PATCH	/scenes/{sceneId}	Update scene
DELETE	/scenes/{sceneId}	Delete scene
POST	/scenes/{sceneId}/assets	Add asset to scene
DELETE	/scenes/{sceneId}/assets/{assetId}	Remove asset from scene

---

Embedded data

Store custom JSON alongside an asset (e.g. physics tuning, video URLs). Path: /api/v1/external/assets/{id}/embedded/{purpose} Supported purposes include physics and videourl.

Method	Description
GET	Read embedded data
POST	Create or replace , body { “data”: { … } }
PATCH	Update , body { “data”: { … } }
DELETE	Remove embedded data

---

Code examples

Python , full Image → Sim flow

import os, time, requests

HOST = "https://dashboard.palatial.cloud"
H = {"x-api-key": os.environ["PALATIAL_API_KEY"]}

with open("product.jpg", "rb") as f:
    resp = requests.post(
        f"{HOST}/api/v1/external/assets/create/imagetosim",
        headers=H,
        files={"file": f},
        data={"name": "Storage Bin", "description": "A plastic bin with hinged lid"},
    )
resp.raise_for_status()
asset_id = resp.json()["id"]

while True:
    st = requests.get(f"{HOST}/api/v1/external/assets/{asset_id}/status", headers=H).json()
    if st["status"] == "READY":
        break
    if st["status"] in ("PROCESSING_FAILED", "PROCESSING_CANCELED"):
        raise RuntimeError(st.get("displayText", st["status"]))
    time.sleep(5)

export = requests.get(
    f"{HOST}/api/v1/external/assets/{asset_id}/media/export",
    headers=H,
    allow_redirects=True,
)
export.raise_for_status()
with open(f"export_{asset_id}.zip", "wb") as out:
    out.write(export.content)

Example asset response (READY)

{
  "id": "…",
  "name": "Storage Bin",
  "type": "imagetosimready",
  "status": {
    "status": "READY",
    "progress": 100,
    "displayText": "Ready"
  },
  "export": {
    "status": "READY",
    "size": 4902028
  },
  "parameters": {
    "engine": ["isaac_sim"],
    "collision_quality": "sdf",
    "agentic_articulation": true
  }
}

---

Support

For API keys, workspace credits, or rate limits, please checkout the Palatial Dashboard.