Desktop - Client Updates v3

Manage the Koldan Windows client's ZIP, MSI, and EXE updates through one global release library and one production feed. Upload a verified package, review its update settings, then publish it explicitly. Clients can fetch the feed and published packages.

Release lifecycle

Published means offered to clients, not installed. Download counts are downloads, not installation confirmations. Changing release defaults never changes an existing publication; changing live settings requires another publication, even for the same package.

A release is READY, ARCHIVED, or REVOKED. Archiving removes it from publication choices while retaining any existing public downloads. Restoring its state to READY makes it eligible again. Revocation is permanent and blocks publication and further server downloads. Replace the active production release before revoking it. Revocation cannot remove files already downloaded to a client.

Administration endpoints

Base path: /api/v1/desktop-services/admin/updates

Endpoint headings and tables show the full request path. {id} is a UUID; {ext} must be exactly zip, msi, or exe, matching the package type.

Upload a release

POST /api/v1/desktop-services/admin/updates/releases

Requires Authentication - Scopes: admin:desktop-updates:write

Admin - Default tenant

Send multipart/form-data with a binary file part and a metadata part whose content type is application/json. The filename extension must match the contents: a ZIP archive, Windows Installer database, or Windows executable. The server computes all supported digests and verifies expectedSha256, if supplied, before accepting the release. ZIPs also undergo archive path and structure validation. Uploaded packages are never executed by the API.

UploadReleaseRequest

These fields belong in the JSON metadata part:

Supply the application's version explicitly; neither the MSI product version nor the filename determines it. Package bytes, type, version, filename, size, and digests cannot be replaced through subsequent edits. Upload a new application version for a different package.

Replace https://api.example.com with your API origin and the example UUIDs with IDs returned by your API. Set ACCESS_TOKEN to an administrator token. Do not store tokens in committed files.

curl -X POST https://api.example.com/api/v1/desktop-services/admin/updates/releases \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F 'file=@./koldan-9.2.0.0.msi' \
  -F 'metadata={
    "version": "9.2.0.0",
    "title": "Koldan 9.2",
    "settings": {
      "mandatory": false,
      "mode": "NORMAL",
      "checksumAlgorithm": "SHA256",
      "releaseNotes": "Improved desktop stability."
    }
  };type=application/json'

A successful response has state: "READY" and publicAvailable: false. Review the package type, size, and verified digest before publishing. Use the same request for ZIP or EXE by changing the file and relevant settings.

ReleaseResponse

Update settings

UpdateSettings

The same settings shape is used for upload defaults, edits, and publication snapshots. A supplied settings object is a complete replacement, not a field-by-field merge: omitted fields receive the defaults below. Omit the entire object to retain existing defaults on edit or use release defaults on publication.

Nonempty executable is rejected for MSI/EXE. No silent-install arguments are supplied automatically; configure and review the switches supported by your installer. The current client uses RunUpdateAsAdmin=false; XML cannot change elevation behavior. Test each installer with the intended Windows privileges.

Get a release

GET /api/v1/desktop-services/admin/updates/releases/{id}

Requires Authentication - Scopes: admin:desktop-updates:read

Admin - Default tenant

Read the release and its quoted revision ETag, for example ETag: "3". To inspect its publication references, list /publications?releaseId={id}. Download unpublished packages using /releases/{id}/package.{ext} with the read permission; the public downloadUrl in the response is unavailable until publication or legacy attestation.

ReleaseResponse

Edit a release

PATCH /api/v1/desktop-services/admin/updates/releases/{id}

Requires Authentication - Scopes: admin:desktop-updates:write

Admin - Default tenant

Send If-Match containing the release ETag. Returns the updated release and a new ETag.

EditReleaseRequest

For example, send {"state":"ARCHIVED","reason":"Superseded by the tested recovery build"} to archive. Send state: "READY" to restore an archived release before publishing it again.

ReleaseResponse

Revoke a release

POST /api/v1/desktop-services/admin/updates/releases/{id}/revoke

Requires Authentication - Scopes: admin:desktop-updates:publish

Admin - Default tenant

Send the release's If-Match and JSON such as {"reason":"Installer withdrawn after compatibility testing"}. Revocation is permanent. Revoking the active production release returns 409; publish its replacement first. Both public and authenticated inspection downloads of a revoked release return 410.

ReleaseResponse

Get production

GET /api/v1/desktop-services/admin/updates/production

Requires Authentication - Scopes: admin:desktop-updates:read

Admin - Default tenant

Returns the current publication, feed URL, and production revision with a quoted ETag and Cache-Control: no-store. Before the first publication, publication is null and revision is 0.

ProductionResponse

Preview a publication

POST /api/v1/desktop-services/admin/updates/publication-previews

Requires Authentication - Scopes: admin:desktop-updates:publish

Admin - Default tenant

Send a PublicationRequest to obtain the proposed snapshot, current publication, generated XML, production revision, and a packageTypeChanged flag. No publication is created. Review installer arguments, mandatory behavior, notes, checksum algorithm, and package-type changes.

For hosted notes, preview XML contains a literal {publicationId} placeholder in the changelog URL; confirmation replaces it with the new publication's ID.

curl -X POST https://api.example.com/api/v1/desktop-services/admin/updates/publication-previews \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "releaseId": "550e8400-e29b-41d4-a716-446655440000",
    "settings": {
      "mandatory": false,
      "mode": "NORMAL",
      "checksumAlgorithm": "SHA256",
      "releaseNotes": "Improved desktop stability."
    },
    "reason": "Approved after Windows installer verification"
  }'

PreviewResponse

Publish or roll back

POST /api/v1/desktop-services/admin/updates/publications

Requires Authentication - Scopes: admin:desktop-updates:publish

Admin - Default tenant

Send the reviewed PublicationRequest with both headers:

The package must be available and the release must be READY. Publication, the production change, and its change-history entry succeed together; a storage or history-persistence failure leaves the existing publication unchanged.

Reuse the same key, identical JSON request, and actor when retrying an uncertain result. A successful replay returns the original publication, including when its original production revision has since changed. Reusing the key for different input or another actor returns 409. A new attempt with a stale revision returns 412: fetch a fresh preview, review the changed production state, and confirm with a new key. A missing If-Match returns 428.

PublicationRequest

To publish exactly the settings reviewed, send the same complete settings and reason used in the preview. Replace "7" below with the preview's production revision, keeping the quotes. Choose a new idempotency key for each new publication attempt; retain it when retrying that same attempt.

curl -X POST https://api.example.com/api/v1/desktop-services/admin/updates/publications \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'If-Match: "7"' \
  -H 'Idempotency-Key: publish-9.2.0.0-review-1' \
  -d '{
    "releaseId": "550e8400-e29b-41d4-a716-446655440000",
    "settings": {
      "mandatory": false,
      "mode": "NORMAL",
      "checksumAlgorithm": "SHA256",
      "releaseNotes": "Improved desktop stability."
    },
    "reason": "Approved after Windows installer verification"
  }'

Rollback uses the same preview and confirmation endpoints. It restores the complete historical snapshot, including settings and descriptive metadata, rather than the release's current defaults. If the historical release is archived, restore it to READY first; revoked releases cannot be restored or published.

First send the rollback body below to /publication-previews and review the restored snapshot. Then confirm using that preview's revision in If-Match ("8" is only an example). The UUID identifies a historical publication, not a release.

curl -X POST https://api.example.com/api/v1/desktop-services/admin/updates/publications \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'If-Match: "8"' \
  -H 'Idempotency-Key: rollback-previous-release-review-1' \
  -d '{
    "restorePublicationId": "8f9760c2-81ac-4c27-9712-f247ce35d682",
    "reason": "Restore the previous verified release"
  }'

Previously published packages remain available after rollback, allowing clients with an earlier manifest to finish their download.

PublicationResponse

Library, publication history, and change history

The collection endpoints below accept zero-based page (default 0) and size (default 50, range 1–200). Results are newest first, with IDs breaking timestamp ties. Responses use items, not content:

{"items": [], "totalElements": 0, "page": 0, "size": 50}

Change history records the actor, impersonator when applicable, UTC timestamp, reason, request ID when available, affected resources, and before/after values. This history is independent of ordinary request-log retention. Significant events are also discoverable in the console at /admin/audit.

Filter action using one of:

• desktop-updates.release.upload
• desktop-updates.release.edit
• desktop-updates.release.revoke
• desktop-updates.release.legacy-import
• desktop-updates.publication.publish
• desktop-updates.publication.rollback

List releases

GET /api/v1/desktop-services/admin/updates/releases

Requires Authentication - Scopes: admin:desktop-updates:read

Admin - Default tenant

Search and paginate the release library using the filters and pagination above.

ReleaseResponse in items

List publications

GET /api/v1/desktop-services/admin/updates/publications

Requires Authentication - Scopes: admin:desktop-updates:read

Admin - Default tenant

Browse immutable publication history, optionally filtered by releaseId, with the pagination above.

PublicationResponse in items

Get a publication

GET /api/v1/desktop-services/admin/updates/publications/{id}

Requires Authentication - Scopes: admin:desktop-updates:read

Admin - Default tenant

Read one immutable publication snapshot, including its reason, actor, and rollback reference.

PublicationResponse

List change events

GET /api/v1/desktop-services/admin/updates/events

Requires Authentication - Scopes: admin:desktop-updates:read

Admin - Default tenant

Browse change history using the actor, release, action, and UTC time filters above.

ChangeResponse in items

Download a package for inspection

GET /api/v1/desktop-services/admin/updates/releases/{id}/package.{ext}

Requires Authentication - Scopes: admin:desktop-updates:read

Admin - Default tenant

Download a library package before publication using an authenticated request. The extension must match the package type. Archived packages remain available; revoked packages cannot be downloaded. See the public download contract for filenames, cache revalidation, and byte ranges.

Package bytes

Response models

ReleaseResponse

ReleaseSnapshot

The immutable snapshot contains releaseId, version, packageType, downloadFilename, sizeBytes, digests, title, and settings. Their types match the release response (releaseId is a UUID). Values are captured at publication and do not follow later edits to the release.

PublicationResponse

ProductionResponse

PreviewResponse

ChangeResponse

Public delivery

Base path: /api/v1/desktop-services/updates/v3

Get the production manifest

GET /api/v1/desktop-services/updates/v3/updates.xml

Public - No authentication or tenant selection required

Returns application/xml;charset=UTF-8 from the current publication, with Cache-Control: no-store. The API generates version, package URL, and checksum; administrators do not upload XML. There is no automatic publication of the newest upload. Before the first publication, the feed returns 503.

XML manifest

Download a published package

GET /api/v1/desktop-services/updates/v3/releases/{id}/package.{ext}

Public - No authentication or tenant selection required

Returns package content directly through the API. The extension must be lowercase and match the stored type. Unknown, unpublished, or extension-mismatched packages return 404; revoked packages return 410. Storage unavailable before streaming returns 503; a failure during streaming can terminate the download, so clients must verify the length and checksum.

Package bytes

Inspect package headers

HEAD /api/v1/desktop-services/updates/v3/releases/{id}/package.{ext}

Public - No authentication or tenant selection required

Return full-package headers without downloading its contents. Content-Length is the complete package size; Range is ignored. Publication eligibility, revocation, storage checks, and ETag revalidation match the download endpoint.

Package headers (no response body)

Get a publication changelog

GET /api/v1/desktop-services/updates/v3/publications/{id}/changelog

Public - No authentication or tenant selection required

Returns the publication's hosted notes as escaped HTML with Cache-Control: no-cache, must-revalidate. Unknown publications return 404; notes for revoked releases return 410. Historical publication notes remain tied to their snapshot. For an external changelog, the manifest points to the configured HTTPS URL.

HTML changelog

Anonymous delivery examples

curl https://api.example.com/api/v1/desktop-services/updates/v3/updates.xml

curl https://api.example.com/api/v1/desktop-services/updates/v3/releases/550e8400-e29b-41d4-a716-446655440000/package.msi \
  --output koldan-9.2.0.0.msi

curl --head https://api.example.com/api/v1/desktop-services/updates/v3/releases/550e8400-e29b-41d4-a716-446655440000/package.msi

curl https://api.example.com/api/v1/desktop-services/updates/v3/releases/550e8400-e29b-41d4-a716-446655440000/package.msi \
  -H 'Range: bytes=0-1023' \
  --output package-first-1024.bin

curl https://api.example.com/api/v1/desktop-services/updates/v3/publications/8f9760c2-81ac-4c27-9712-f247ce35d682/changelog

Discovery and legacy URL migration

Anonymous GET /api/v1/global/siteproperties and the gRPC site-properties response expose the additive updatesUrlV3 field. By default, both updatesUrlV2 and updatesUrlV3 point to /api/v1/desktop-services/updates/v3/updates.xml on the advertised HTTP origin. This lets existing clients use v3 through their existing v2 discovery field. Explicit URL overrides remain in effect and must be migrated deliberately. See site properties for exact configuration names.

Legacy URL migration

Only a single filename under the v2 base is resolved. Inventory any additional XML names or nested legacy paths and configure explicit proxy redirects for them. The old local-file and wyUpdate delivery mechanisms are retired; existing updatesUrl discovery fields remain for wire compatibility.

Back up old XML and packages, then upload each package through the normal verification endpoint with its original filename, application version, settings, and expected SHA-256. When a historical package must remain public without selecting it as production, record legacy provenance using the following endpoint.

Attest a legacy import

POST /api/v1/desktop-services/admin/updates/releases/{id}/legacy-import

Requires Authentication - Scopes: admin:desktop-updates:publish

Admin - Default tenant

Send If-Match containing the release revision and JSON such as {"reason":"Imported previously published v2 installer; backup and checksum verified"}. The release must be READY and storage must be available. The response is the updated release and ETag. This operation makes that package publicly available and records the attestation in change history; it does not change the production feed.

ReleaseResponse

Verify imported package bytes, filename redirects, and the initial v3 publication before switching discovery. Follow the PVC transition procedure before retiring the old volume.

Error responses

The status tables above highlight endpoint-specific outcomes. Every administration method also returns 401 for missing or invalid credentials or 403 for insufficient scope or default-tenant authority.

Errors use the API's problem-detail response where applicable; use the status and detail to guide recovery. Preserve request correlation identifiers when reporting failures.