OpenSkin API endpoint

Create a viewer scene

POST /v2/scenes

Creates the first revision of a schema version 3 scene document. A scene contains presentation settings, not item identity or visual item state.

Authentication

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

Parameters

Name	Location	Required	Description
`Idempotency-Key`	header	Yes	See the OpenAPI schema for accepted values.

Request body

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

Response meaning

201: Scene created; the response returns a quoted ETag containing the SHA-256 of the normalized scene JSON
401: V2Unauthorized
403: V2Forbidden
409: Idempotency key reused with different content

Request example

curl 'https://api-v2.openskin.dev/v2/scenes'\
  -X POST\
  -H 'X-API-Key: osk_live_...' \
  -H 'Idempotency-Key: example-Idempotency-Key' \
  -H 'Content-Type: application/json' \
  --data '{"schema":3,"kind":"openskin-viewer-scene","name":"example-name","revision":1,"presentation":{"background":{"type":"color","value":"#202020"},"camera":{"preset":"inspect"},"quality":"interactive"},"chrome":{"showControls":false,"allowFullscreen":false,"watermark":null}}'

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.

Last updated 2026-09-04.