# Turboism update API v1

The new service is https://api.turboism.dev. The legacy Updates service is independent and is not read or changed by this system.

## Public endpoints

- GET /v1/releases/stable.json — published stable product releases
- GET /v1/releases/beta.json — published prereleases excluding nightly
- GET /v1/releases/nightly.json — daily changed-only development channel
- GET /health — synchronization and mirror configuration status

Successful JSON responses support ETag/If-None-Match, HTTP 304, HEAD, and public CORS. No user login or token is needed. Installers are downloaded directly from listed sources, not through the www application.

## Responses

HTTP 200 with `status: ready` contains `release.version`, `release.channel`, `release.buildNumber`, `release.sourceRevision`, `release.publishedAt`, exact release notes, and four binary assets. Each asset includes `size`, `sha256`, `kind`, `sources` and a matching checksum sidecar.

`buildNumber: null` explicitly means historical build identity is unknown. Never derive it from Release IDs, timestamps, synchronization order or the legacy site's numbering.

HTTP 200 with `status: not_published` and `release: null` means a complete successful GitHub query found no published release in that channel. A draft or a Git tag alone is not a release.

HTTP 503 with `status: unavailable` and `release: null` means the update result is unknown. Honor Retry-After and retry with backoff. Do not display "up to date" after a failed request. Invalid channel routes return 404; unsupported methods return 405.

## Download sources and integrity

`github` is the exact canonical GitHub Release asset. `official` is present only after all matching files have been uploaded and verified in the new isolated R2 storage. Never invent a mirror URL or assume that a missing source is available. Verify the selected file's expected size and SHA-256 before installation, regardless of source. A checksum is not a code-signing certificate or notarization.

Official mirror URLs use `/files/<sha256>/<filename>` on api.turboism.dev. They support HEAD, single byte ranges and If-Range for identical bytes. Restart a partial download if the file identity changes. R2 mirror activation requires separate storage permissions; the metadata API can operate with GitHub-only sources before that is configured. Global Cloudflare delivery is not a mainland-China speed guarantee.

## Version and channel rules

Store the user's selected channel. Never automatically switch stable users to beta/nightly, and never downgrade to a lower product series just because its build number is larger. Compare SemVer first within eligible channels/compatibility; buildNumber distinguishes concrete builds, not maturity. `beta.10 > beta.2`, a final version follows its prereleases, and `+build.*` does not affect SemVer precedence. Future nightly versions can use `X.Y.Z-0.nightly.N`.

HTTP 304 means reuse the previously retrieved JSON; it does not by itself mean the installed client is current. This API supplies update information, not live replacement of files in a running Cubism process.

## Automatic synchronization

Published GitHub Releases are the source of truth. OIDC-authenticated GitHub Actions notifications request a refresh when releases change or the protected publisher completes. Scheduled reconciliation runs every 15 minutes. Product binaries are not rebuilt during synchronization. Withdrawn releases stop being advertised; historical storage is not automatically deleted. The build allocator, source-bound receipt and product release workflow remain separate from this read-only website.


## Daily Nightly publication

The product workflow checks main at 04:20 Asia/Shanghai each day. It only builds
when the fixed source commit differs from the last successfully published
Nightly. No changes means no build number, build or new Release. Failed builds
and unfinished drafts never advance that baseline. Manual runs obey the same
check. Nightly is a separate prerelease lane (`X.Y.Z-0.nightly.N`, N=buildNumber),
not GitHub's stable latest. GitHub scheduling is best effort and may be delayed.