Create a 3D viewer session

Authentication

Send a Platform API key with permission to use this endpoint in the X-API-Key header.

Parameters

This operation has no URL parameters.

Request body

The example includes every required JSON field. Open OpenAPI JSON to see optional fields, accepted values, and limits.

Response meaning

201

Short-lived viewer session and exact scene receipt

400

Invalid item or scene selector

401

V2Unauthorized

403

V2Forbidden

404

Scene, scene revision, or renderer item not found

503

Renderer session creation unavailable

Request example

curl 'https://api-v2.openskin.dev/v2/viewer/sessions'\
  -X POST\
  -H 'X-API-Key: osk_live_...' \
  -H 'Content-Type: application/json' \
  --data '{"item":{"item":{"family":"weapon","definition_index":1},"state":{}},"scene_id":"00000000-0000-4000-8000-000000000000"}'

Limits and retries

Check the listed status codes before retrying. If a request uses a unique request key, reuse that key only when repeating the same request. If a list returns next_cursor, send it unchanged in the next request.