Files, assets, and depots

A release can carry more than one kind of file. The distinction matters when an update client decides what to install.

File	What it represents	Example
Artifact	An installable build for one platform, architecture, and format	field-notes.apk, FieldNotes.msix
Asset	An extra file attached to a release or to one artifact	Symbols, license, checksums, an update payload
Depot	A named, versioned file set that a release pins	base, voice-en, high-res-textures

Uploading an artifact creates or finds a release by app + version + build number. Further artifact uploads with the same version and build number join that release. Assets and depots attach to an existing release; they do not create one. Upload alone leaves the release as a draft. Promote it to a channel when it is ready for delivery. See Releases and channels.

Artifacts: the installable build

An artifact has a platform (android, ios, macos, windows, or linux), an architecture (arm64, x64, universal, armv7, or x86), and a format such as apk, ipa, msix, or zip. Its record includes size, SHA-256, SHA-512, and any package metadata the server could extract. It also has a variant (default unless you declare others). One release cannot contain two artifacts with the same platform, architecture, format, and variant.

For example, upload an Android APK and a Windows MSIX under the same release:

export RD_URL="https://releases.example.com"
export RD_TOKEN="rd_your_upload_token"

rdesk upload --org "$ORG_ID" --app "$APP_ID" \
  --file ./dist/field-notes.apk --version 2.1.0 --build 210 \
  --platform android --arch arm64 --format apk

rdesk upload --org "$ORG_ID" --app "$APP_ID" \
  --file ./dist/FieldNotes.msix --version 2.1.0 --build 210 \
  --platform windows --arch x64 --format msix

Both commands print a release_id; it is the same for both uploads. Keep an artifact ID from the API response when an extra file belongs to one particular artifact. The upload API accepts raw bytes, not multipart form data; see Upload an artifact and Publish your first release.

Assets: extra release files

An asset has a role and a safe download name. Supported roles are payload, delta, manifest, symbols, signature, checksums, license, docs, depot, and other. Supply artifactId when the file is specific to one artifact; omit it for a release-wide file. required=true marks an asset as required for an update client. The server records hashes and signs the asset's role, name, and SHA-256 when an app signing key is active.

For example, attach symbols only to the Windows build, then attach release-wide checksums:

rdesk asset --org "$ORG_ID" --app "$APP_ID" --release "$RELEASE_ID" \
  --artifact "$WINDOWS_ARTIFACT_ID" --role symbols --file ./dist/FieldNotes.pdb

rdesk asset --org "$ORG_ID" --app "$APP_ID" --release "$RELEASE_ID" \
  --role checksums --file ./dist/SHA256SUMS

You can also attach files during rdesk upload: --asset symbols=./dist/FieldNotes.pdb attaches to the just-uploaded artifact, while --release-asset checksums=./dist/SHA256SUMS attaches to the release. The separate asset command works after upload.

For direct HTTP upload, send raw bytes to POST /api/v1/orgs/:orgId/apps/:appId/releases/:releaseId/assets with role, name, and optional artifactId, required, fromReleaseId, and JSON metadata query parameters. An upload token or developer session can upload; a viewer session can request an asset download link. The response is { "asset": ..., "manifest": ... }. The manifest value is usually null.

Payload archives and per-file manifests

Use the payload role for an archive consumed by an in-place updater. Accepted names end in .zip, .tar.gz, .tgz, .tar.xz, or .tar.zst. The server checks archive type. For ZIP and tar.gz/tgz, it also validates the archive and generates a separate manifest asset with each file's path, size, SHA-256, and permission bits. The manifest records the payload archive's SHA-256 so an updater can verify that the files and archive belong together. Invalid supported archives are rejected.

For example:

rdesk asset --org "$ORG_ID" --app "$APP_ID" --release "$RELEASE_ID" \
  --role payload --file ./dist/field-notes-payload.zip --required

The upload response supplies both asset IDs. GET /releases/:releaseId/assets/:manifestAssetId/manifest returns the parsed file list. To compare two manifest assets, call GET /releases/:releaseId/assets/:newManifestAssetId/manifest-diff?from=:oldManifestAssetId; the response lists added, removed, and changed paths plus an unchanged count. A file counts as changed if its SHA-256 or permission bits differ. These endpoints require a viewer session. Tar.xz and tar.zst payloads are accepted, but currently do not get a generated per-file manifest.

Depots: reuse unchanged content between releases

A depot is a named slot for content distributed alongside a build. Define it once for an app, then pin a version of it to each release that needs it. Each pin points to an asset and has a human-readable versionLabel. A depot can be required or optional and can be limited to one platform and/or architecture. A null platform or architecture means no restriction for that field.

Suppose a game ships a small executable and two content packs:

Depot key	Required?	Release 2.1	Release 2.2
base	Yes	Upload version 5	Inherit version 5
voice-en	No	Upload version 3	Upload version 4

The 2.2 release reuses the stored base file rather than uploading it again. The inherited pin has its own asset record, while storage keeps the shared file until no release references it. An optional depot is offered to clients that request it; a required depot is part of the normal install set.

Create and pin a depot

Depot management is under /api/v1/orgs/:orgId/apps/:appId/depots. Creating and deleting definitions requires an admin session. The key uses lowercase letters, digits, and dashes, up to 48 characters; name is a display label.

curl -X POST "$RD_URL/api/v1/orgs/$ORG_ID/apps/$APP_ID/depots" \
  -H "Content-Type: application/json" -H "Cookie: $RD_SESSION_COOKIE" \
  -d '{"key":"base","name":"Base content","platform":null,"arch":null,"optional":false}'

Save the returned id as DEPOT_ID. Upload one version to an existing release with a developer session or upload token:

curl -X PUT --data-binary @./dist/base.pak \
  -H "Authorization: Bearer $RD_TOKEN" \
  "$RD_URL/api/v1/orgs/$ORG_ID/apps/$APP_ID/depots/releases/$RELEASE_ID/$DEPOT_ID?name=base.pak&versionLabel=5"

The response includes the depot key, version label, inherited: false, and the asset. A release can pin each depot only once; remove its existing pin before replacing it. The dashboard's release page also provides depot upload, inheritance, and removal controls.

Inherit an unchanged version

After creating the next release, inherit its missing depot pins:

curl -X POST "$RD_URL/api/v1/orgs/$ORG_ID/apps/$APP_ID/depots/releases/$NEXT_RELEASE_ID/inherit" \
  -H "Authorization: Bearer $RD_TOKEN" -H "Content-Type: application/json" \
  -d '{"depotIds":["'"$DEPOT_ID"'"]}'

Omit depotIds to consider every app depot. Omit fromReleaseId to use the newest earlier release that pins each depot; supply it to select a particular earlier release. Already-pinned depots are skipped, and the response's inherited array names the keys actually copied. GET /depots/releases/:releaseId lists pins, version labels, inherited flags, and assets. Removing a pin or deleting an old release does not delete a shared file while another pin still uses it.

What update clients receive

The generic JSON feed includes eligible artifacts, extra assets, and pinned depots. An updater should verify the signed feed and each downloaded file's SHA-256 before installing. The SDK's resolveDepots selects all required depots plus requested optional keys, then skips versions already installed; downloadDepots downloads and verifies selected files into <directory>/<depot-key>/<asset-name>. Store installed versionLabel values locally so the next check can avoid unchanged depot downloads.

Depots follow the release selected by the channel and rollout. Promoting a release does not automatically copy depot pins from an earlier release, so upload or inherit the pins you intend that release to carry before promotion. See Update feeds and Public pages and downloads for delivery behavior.