The two calls
Updates take two requests, not one. The check runs at launch and only needs the version. The second runs on click and needs a link. The documented response for a valid license looks like this, with a signed url per file:
{ "version": "3.2.1", "notes": "Fixes a crash when importing large files.",
"published_at": "2026-11-19T08:30:00.000Z",
"files": [ { "id": 12, "filename": "Inkwell-3.2.1.dmg", "size": 50540748,
"platform": "macos", "url": "https://clavem.io/d/12?exp=...&sig=..." } ] }
With no key, or a key that does not qualify, you get only version and published_at. If nothing is published, the endpoint answers 404 with not_found. I captured that last one from the live API on 19 November 2026.
Check and compare
// pubspec.yaml: http, package_info_plus, pub_semver
import 'dart:convert';
import 'dart:ffi' show Abi;
import 'dart:io';
import 'package:http/http.dart' as http;
import 'package:package_info_plus/package_info_plus.dart';
import 'package:pub_semver/pub_semver.dart';
const _base = 'https://clavem.io';
const _productId = 75; // from your product page
class Latest {
Latest(this.version, this.notes, this.fileName, this.size, this.url);
final Version version;
final String? notes;
final String? fileName, url; // null unless the license may download
final int? size;
}
class UpdateCheckFailed implements Exception {
UpdateCheckFailed(this.status, this.retryAfter);
final int status;
final int? retryAfter; // seconds, from the Retry-After header
}
/// Newest published release, or null when nothing is published or the version is not semver.
Future<Latest?> fetchLatest(String licenseKey) async {
final platform = Abi.current().toString(); // for example macos_arm64: label your files the same way
final res = await http.get(
Uri.parse('$_base/v1/releases/$_productId/latest?platform=$platform'),
headers: {'X-License-Key': licenseKey}, // the header keeps the key out of logs and URLs
).timeout(const Duration(seconds: 8));
if (res.statusCode == 404) return null;
if (res.statusCode != 200) {
throw UpdateCheckFailed(res.statusCode, int.tryParse(res.headers['retry-after'] ?? ''));
}
final j = jsonDecode(res.body) as Map<String, dynamic>;
final withLink = ((j['files'] as List?) ?? const [])
.cast<Map<String, dynamic>>()
.where((f) => f['url'] != null)
.toList();
try {
return Latest(
Version.parse(j['version'] as String),
j['notes'] as String?,
withLink.isEmpty ? null : withLink.first['filename'] as String,
withLink.isEmpty ? null : withLink.first['size'] as int,
withLink.isEmpty ? null : withLink.first['url'] as String,
);
} on FormatException {
return null; // "2026.11" or "4.0" is not a three-part version
}
}
Future<bool> isNewer(Latest latest) async {
final current = Version.parse((await PackageInfo.fromPlatform()).version);
if (latest.version.isPreRelease && !current.isPreRelease) return false; // a beta never replaces a stable install
return latest.version > current;
}
Three details matter here.
- Latest means most recently published, not highest version. If you publish a 3.2.2 backport after 3.3.0, the endpoint returns 3.2.2, and
latest.version > currentkeeps a 3.3.0 user from being offered a downgrade. - Versions must parse. Clavem accepts versions up to 64 characters with letters, digits, dots, dashes, plus signs and underscores.
pub_semverwantsmajor.minor.patch. Keep your release versions in that shape. PackageInfo.versioncomes fromversion:inpubspec.yaml, without the+buildpart, so3.2.1+7reads as3.2.1.
Platform labels
A label is any string you chose when you uploaded the file, such as macos_arm64. Abi.current() already names the architecture, so a label per ABI needs no mapping table. A file with no label is offered to every platform. If you use only macos for both Apple Silicon and Intel disk images, you have to pick between two files in the response yourself.
Download on click, and resume
Future<File> download(Latest l, Directory dir, void Function(int got, int? total) onProgress) async {
final target = File('${dir.path}/${l.fileName}');
final part = File('${target.path}.part'); // the name carries the version, so a stale partial never matches
final have = await part.exists() ? await part.length() : 0;
if (have > 0 && have == l.size) return part.rename(target.path); // finished earlier, never renamed
final client = http.Client();
try {
final request = http.Request('GET', Uri.parse(l.url!))..headers['Range'] = 'bytes=$have-';
final res = await client.send(request);
if (res.statusCode != 200 && res.statusCode != 206) {
throw HttpException('Download failed: HTTP ${res.statusCode}');
}
final resumed = res.statusCode == 206; // the server honoured the range
final sink = part.openWrite(mode: resumed ? FileMode.append : FileMode.write);
var got = resumed ? have : 0;
final length = res.contentLength;
final total = length == null ? null : length + (resumed ? have : 0);
await for (final chunk in res.stream) {
sink.add(chunk);
got += chunk.length;
onProgress(got, total);
}
await sink.close();
return part.rename(target.path);
} finally {
client.close();
}
}
Call fetchLatest again right before download. The link from the launch check may be older than the hour it lives for. Downloads support byte ranges, so a dropped connection resumes. A 403 means the link expired, and the answer is a fresh fetchLatest, not a retry.
Applying the update
Clavem has no updater and no delta updates, and the release response has no checksum field, so verification is yours. On desktop, open the downloaded installer and quit:
Future<void> openInstaller(File f) async {
if (Platform.isMacOS) {
await Process.run('open', [f.path]);
} else if (Platform.isWindows) {
await Process.start(f.path, [], mode: ProcessStartMode.detached);
} else {
await Process.run('xdg-open', [f.parent.path]);
}
exit(0); // a running Windows executable cannot be overwritten
}
This file imports dart:io and dart:ffi, so it is desktop-only: keep it out of web builds with a conditional import. On iOS, and on Android builds from Google Play, the store delivers updates. This endpoint is for builds you distribute yourself. On web, you deploy the new bundle, so there is nothing to download.
Rate limits and failures
The releases endpoint allows 120 requests per minute per IP address, counted apart from validation, so a launch check never eats your validation budget. A 429 carries Retry-After: 60. For an automatic check at launch, swallow UpdateCheckFailed and try again next launch. For a button the customer pressed, show “try again in a minute”. Do not poll.
Doing this with Clavem
Upload each build once on the product page, give it a platform label, and publish. Buyers get the same files from their order page. The full endpoint, with limits and imported-license behavior, is in Releases and downloads. The key check that decides whether a link comes back is described in validation in Flutter.
Questions
Does the releases endpoint need a license key?
No. Without a valid key it still returns the newest version and its publish date, which is enough to say an update exists. Release notes and file links appear only for a key that belongs to this product and is neither expired nor disabled.
Why does the download link stop working?
Links are signed and last one hour. Ask the endpoint for a new one when the customer clicks Update, not when the version check runs.