Upload API

The Upload API is an HTTP API that allows you to upload craft items and accessories.

By calling the Upload Init endpoint, you can obtain the Upload URL and Status URL. By calling the obtained URLs in order, you can upload PITM data and thumbnail images and check the validation results.

The sample code (Python) includes wrappers for these processes.

https://github.com/ClusterVR/PITMSample/blob/main/python/cluster_api.py

Uploaded File

The Upload API receives the PITM data and thumbnail image as a single zip file.

In the zip file, place only the following two files in /.

For craft items

• item_template.glb: Craft item (PITM data format)
• icon.png: Thumbnail image (512px x 512px opaque PNG)

For accessories

• accessory_template.glb: Accessories (PITM data format)
• icon.png: Thumbnail image (512px x 512px opaque PNG)

Upload Init Endpoint

POST https://api.cluster.mu/v1/upload/item_template/policies (craft item)

POST https://api.cluster.mu/v1/upload/accessory_template/policies (accessory)

Notifies the start of upload and obtains the Upload URL for the file body and the Status URL.

Please set the following in the HTTP header.

• Content-Type: “application/json”
• X-Cluster-Access-Token: The uploader’s CCK access token
• X-Cluster-App-Version: “2.0.0”
• X-Cluster-Device: “ClusterCreatorKit”
• X-Cluster-Platform: “ClusterCreatorKit”
• X-Cluster-Platform-Version: “api--” (e.g. “api-itemcreator-0.5”)

Note: Make sure you use the uploader’s CCK access token, not the tool developer’s.

Craft Items

{
    "contentType": "application/zip",
    "fileName": "item_template.zip",
    "fileSize": 123456, // zip file size (bytes)
    "isBeta": false // true if uploading as beta item, false otherwise
}

response Normal: 201 Created

{
  "form": {...}, // data to be used with Upload URL
  "itemTemplateID": "12345678-abcd-1234-abcd-12345678abcd", // newly issued ID
  "uploadUrl": "https://file-storage.cluster.mu/xxxxxx",
  "statusApiUrl": "https://upload-status.cluster.mu/item_template/xxxxxxxxxxxxxx"
}

The itemTemplateID obtained here can be used at https://docs.cluster.mu/script/en/classes/ItemTemplateId.html. The Upload URL can be obtained from uploadUrl, and the Status URL can be obtained from statusApiUrl.

accessories

{
    "contentType": "application/zip",
    "fileName": "accessory_template.zip",
    "fileSize": 123456, // zip file size (bytes)
}

response Normal: 201 Created

{
  "form": {...}, // data to be used with Upload URL
  "accessoryTemplateID": "12345678-abcd-1234-abcd-12345678abcd", // newly issued ID
  "uploadUrl": "https://file-storage.cluster.mu/xxxxxx",
  "statusApiUrl": "https://upload-status.cluster.mu/accessory_template/xxxxxxxxxxxxxx"
}

The Upload URL can be obtained from uploadUrl, and the Status URL can be obtained from statusApiUrl.

Calling Upload URL

By doing a POST to the Upload URL, you upload the file content and start the validation. Each Upload URL only allows single call.

The content of form is treated as an HTTP form, and the zip file is POSTed as “item.zip” (MIME type: “application/zip”).

Use the Status URL to check the upload and validation results.

Calling Status URL

By performing a GET to the Status URL, you can get information on whether the upload was successful or not. Even after completing the POST to the Upload URL, it may take some time for the server’s internal processing and validation. This usually takes a few seconds to complete. The Status URL can be called multiple times. It is recommended to poll about once per second. If it is not completed after 120 seconds, consider the upload to have failed and stop polling the Status URL.

response

{
    "status": "...",
    "reason": "..."
}

• status: One of "VALIDATING", "ERROR", or "COMPLETED"
  • VALIDATING: Validating the uploaded content
  • COMPLETED: Upload successful
  • ERROR: Validation error or upload failure for some reason.
• reason: Details of the validation error if status is "ERROR".