Moshpit Studio

API Reference

/

POST /v1/splats

POST /api/v1/splats

Commit an uploaded single-file or LOD Scene to the external user's library. This endpoint verifies the uploaded objects, reserves the user's storage quota, creates the Scene record, and adds default viewer/editor settings.

POST

https://moshpit.studio/api/v1/splats

Auth

All three headers are required:

Authorization: Bearer msk_YOUR_SECRET_KEY
X-Moshpit-Public-Key: mpk_YOUR_PUBLIC_KEY
X-Moshpit-External-User-Id: YOUR_HOST_USER_ID

For a single-file Scene, splatUrl must be the fileUrl returned from POST /api/v1/uploads/splat-file. For an LOD Scene, use the manifestUrl and folderKey returned from POST /api/v1/uploads/lod-folder. All upload values must belong to the same external user.

REST API access

REST API access is included on Free, Pro, and Enterprise. Storage, Scene counts, and integration limits still apply.

Body

{}

JSON

{
  "title": "Lobby scan",
  "description": "Optional notes",
  "visibility": "private",
  "splatUrl": "https://cdn.example.com/splats/embed/...",
  "splatType": "file",
  "imageUrl": "https://cdn.example.com/splat-images/external-user/thumbnail.webp",
  "thumbnailDepthUrl": "https://cdn.example.com/splat-images/external-user/depth.jpg",
  "initialCameraPosition": [0, 1.5, 4],
  "initialCameraRotation": [-10, 0, 0]
}

visibility defaults to private, and splatType defaults to file. Upload imageUrl and thumbnailDepthUrl through POST /api/v1/uploads/splat-images. If you provide thumbnailDepthUrl, you must also provide imageUrl. Camera and transform arrays are optional three-number tuples. Omitted values use Studio defaults.

For an LOD Scene, replace the upload fields with:

{}

JSON

{
  "splatType": "lod",
  "splatUrl": "https://cdn.example.com/splats/external-user/lod-.../lod-meta.json",
  "lodFolderKey": "splats/external-user/lod-.../"
}

Success response

{}

JSON

{
  "status": "success",
  "splatId": "65f1a2b3c4d5e6f7a8b9c0d1",
  "splat": {
    "id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "title": "Lobby scan",
    "visibility": "private",
    "externalUserId": "host_user_123",
    "isOwner": true
  },
  "usage": {
    "usedBytes": 17825792,
    "limitBytes": 21474836480,
    "remainingBytes": 21457010688,
    "percentUsed": 0.08
  }
}

usage.limitBytes is derived from the integration owner's Studio account storage meter. Host applications do not provide this value.

Error responses

StatusCause
400Invalid JSON, invalid fields, missing external user, or invalid upload URL
401Missing or invalid Bearer / public-key combination
403Uploaded object does not belong to the external user
404External user not found
413External user storage quota exceeded

If commit fails because of quota or database creation, Studio attempts to remove the uploaded object so the bucket and quota stay consistent.

Previous

POST /v1/uploads/splat-images

Next

GET /v1/splats/{id}