Build Uploads

WebGL build structure

The zip must contain index.html and a *.loader.js file:

your-build.zip
├── index.html          ← required
├── Build/
│   ├── game.loader.js  ← required
│   ├── game.wasm
│   ├── game.data
│   └── game.framework.js
└── TemplateData/

A single wrapping folder is fine — if Unity exports to WebGLBuild/, the upload strips that prefix for you. What fails is a zip with several top-level folders and no index.html inside any single one. __MACOSX/ and ._ entries created by macOS are ignored automatically.

A zip without index.html or a *.loader.js file fails processing. The version is listed as failed with the reason, and you can upload it again with the same version number.

Archive limits

Limit	Value
Files in the archive	1,000
Single file, uncompressed	200 MB
Whole archive, uncompressed	1.5 GB
The zip itself	500 MB

The zip size, the file count and the total size are checked before extraction, so an oversized build fails fast. The single-file limit is checked as each file is extracted.

Upload via Developer Portal

Developer Portal → your game → Builds → Upload Build
The platform is always WebGL — SusaPlay runs WebGL builds only
Set version ID as x.y.z, such as 1.0.0, optionally with a suffix such as 1.0.0-beta
Add release notes — describe what changed and how to test
Upload zip

After the upload, the portal shows Processing build… while SusaPlay extracts the build, usually under a minute. The version then appears as pending_review, or as failed with the reason. For a private game it appears as ready instead: ready to test, and not sent for review. To play a build that is not live yet, use the buttons on its row:

Button	What it does
Preview	Opens the build on the player site with a single-use link that expires in 30 minutes
Share	Creates a 30-day link anyone can open, and copies it. Copy and Revoke appear under the build. Sharing again returns the same link; revoking cuts everyone off

Both work for pending_review and ready WebGL builds. A link stops working once the build goes live, is rejected or is deleted.

Upload via CI/CD

Your pipeline uses the same three steps the portal uses, authenticated with your developer API key. The zip goes straight to storage, not through the API, up to 500 MB.

1. Ask for a signed upload URL

UPLOAD_URL=$(curl -sS -X POST https://api.susaplay.com/catalog/get-upload-url \
  -H "Authorization: ApiKey $DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"gameId\":\"$GAME_ID\",\"versionId\":\"$VERSION\",\"platform\":\"webgl\"}" \
  | jq -r '.data.uploadUrl')

The URL is valid for 20 minutes. This call fails early if the version already exists or you are at the review cap, so you find out before uploading anything.

2. Upload the zip

curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --upload-file ./dist/game.zip

3. Register the build

curl -sS -X POST https://api.susaplay.com/catalog/process-build \
  -H "Authorization: ApiKey $DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"gameId\":\"$GAME_ID\",\"versionId\":\"$VERSION\",\"platform\":\"webgl\",\"notes\":\"Build $CI_COMMIT_SHA\"}"

SusaPlay checks the request and answers 202 with "status": "processing". It then extracts the build in the background.

4. Wait for processing (optional)

Poll the version until it leaves processing and extracting:

while true; do
  STATUS=$(curl -sS "https://api.susaplay.com/catalog/game/$GAME_ID/versions/$VERSION" \
    -H "Authorization: ApiKey $DEVELOPER_API_KEY" | jq -r '.data.version.status')
  case "$STATUS" in
    processing|extracting) sleep 5 ;;
    pending_review) echo "Build is waiting for review"; break ;;
    ready) echo "Build is ready to test (private game)"; break ;;
    *) echo "Build $STATUS"; exit 1 ;;
  esac
done

A failed version carries the reason in .data.version.failure.message. Fix the build and upload it again with the same version number. A key with only the builds:write permission may poll.

Changed in October 2026: process-build used to extract the build before answering, so a large build could time out while it still succeeded. It now answers 202 at once. A pipeline that only checks success: true keeps working, but that no longer means the build is ready.

The old single-call POST /catalog/publish endpoint has been removed. It sent the zip in the request body, which caps at 32 MiB — smaller than most WebGL builds. Move any pipeline still calling it to the three steps above.

Remote content ships separately — see Addressables for updating levels or art without a new build.

Build retention

SusaPlay keeps a limited number of builds per game and deletes older ones automatically, along with their files.

Rule	Value
Builds kept per game	5 most recent
Grace period before a build can be removed	24 hours
Builds you can have in review at once	3

Never deleted automatically: the live build, a build waiting for review or still processing, and anything uploaded within the grace period. A ready build of a private game is not under review, so it is kept like any other build: among the 5 most recent. A failed build is deleted by your next successful upload and does not count toward the 5. Subscribe to the BUILD_PRUNED webhook if your pipeline needs to know when a version was removed. Builds still processing count toward the review cap. Uploading past the cap is rejected with 409 until one of your pending builds is reviewed, so ask for a review rather than queueing more builds. You cannot delete a build yourself; contact support if one must be removed.

Version states

State	Meaning
`processing`, `extracting`	Uploaded; SusaPlay is extracting the build. After 15 minutes in this state it reads as `failed` with code `PROCESSING_TIMEOUT`, and the same version can be uploaded again
`failed`	Processing failed — `failure.message` says why; upload again with the same version
`pending_review`	Submitted, awaiting review
`ready`	Processed build of a private game — playable with Preview and Share, not under review
`live`	Currently served to players
`deprecated`	Replaced by a newer live version
`rejected`	Failed review — fix issues and resubmit

A passing review moves a version straight to live. There is no separate approved-but-not-live state.

Release notes checklist

Good release notes help reviewers pass builds faster:

What changed since last version
Known issues or workarounds
Test account credentials if auth is required
Which browsers and devices were tested

Getting Started

Integration

SDK

API

WebGL build structure

Archive limits

Upload via Developer Portal

Upload via CI/CD

1. Ask for a signed upload URL

2. Upload the zip

3. Register the build

4. Wait for processing (optional)

Build retention

Version states

Release notes checklist

​WebGL build structure

​Archive limits

​Upload via Developer Portal

​Upload via CI/CD

​1. Ask for a signed upload URL

​2. Upload the zip

​3. Register the build

​4. Wait for processing (optional)

​Build retention

​Version states

​Release notes checklist

WebGL build structure

Archive limits

Upload via Developer Portal

Upload via CI/CD

1. Ask for a signed upload URL

2. Upload the zip

3. Register the build

4. Wait for processing (optional)

Build retention

Version states

Release notes checklist