release-publish

REST API 与 JSON-RPC

本页是协议参考(英文)。中文入门见 快速接入,错误码的处理方式见 错误码,下架/上架见 管理面板。

One server hosts the release packages of all your apps and tells them when a newer build exists. Everything is available as REST and as JSON-RPC 2.0 (same operations, same types), and the Go SDK (relhub/pkg/relclient) wraps both.

Concepts

Term Meaning
app Something you ship. Id ^[a-z][a-z0-9-]{1,31}$, e.g. nightdesk. Created explicitly.
platform A build target of an app: android, win-x64, linux-arm64, … (^[a-z0-9][a-z0-9_-]{0,23}$, your naming). Each platform has its own version sequence.
release One uploaded package. Identified by (app, platform, versionCode); the file never changes. versionCode is an integer that must be higher than every earlier one of that platform (409 otherwise). For Android it must equal the APK's versionCode. versionName ("1.6.1") is for people.
channel What clients on that channel are offered: a pointer to one release plus a minVersionCode. stable is the default; add beta, nightly, … (^[a-z][a-z0-9-]{0,15}$) just by publishing or promoting to them.
minVersionCode Clients running a lower versionCode must update (mandatory: true). 0 = none.
yank Withdraws a release: it can no longer be offered or downloaded. A release a channel still offers cannot be yanked.
manifest The signed description of what a channel offers (below).

Conventions

  • Base URL: the server's address plus whatever path prefix the reverse proxy adds, e.g. https://tony-ai-pc-1.tail9f7f1f.ts.net/release. All paths below are relative to it.

  • JSON in, JSON out, UTF-8. Times are RFC 3339 UTC.

  • Errors: HTTP status plus {"error":{"code":"…","message":"…"}}.

    code HTTP typical cause
    invalid_argument 400 bad id, missing field, bad JSON
    unauthorized 401 no / invalid token (WWW-Authenticate: Bearer)
    forbidden 403 token may not touch this app / needs admin
    app_delisted 403 an admin delisted the app; anonymous reads and downloads of it are refused (see Admin)
    not_found 404 unknown app, platform, channel, release; nothing published yet
    conflict 409 versionCode not higher; yanking a release that is still offered
    too_large 413 package over the server limit (default 2 GiB)
    unavailable 503 too many waiting clients; package missing on disk
    internal 500 server bug
  • Auth: reading is open (the server is meant to sit on a private network behind a reverse proxy). Writing needs Authorization: Bearer <token>: the admin token (<data>/admin.token) or an app-scoped token from relhub token create -app a,b, which may publish/promote/yank only for its apps. A bad token on a public read is ignored; on a write it is 401.

  • Responses are Cache-Control: no-store, except package downloads (below).

How an app updates itself

every launch and every few hours (or a long-poll watch):
  GET v1/apps/{app}/check?platform=P&channel=stable&versionCode=<installed>
  → verify manifest signature with the pinned public key
  → updateAvailable?  no  → done
                      yes → mandatory? block the UI until updated
  GET {base}/{downloadPath}        (Range-resume if interrupted)
  → check size and sha256 against the manifest
  → hand the file to the installer (Android: PackageInstaller / Windows: replace + restart)

Rules that keep this safe:

  1. Pin the signing public key(s) in the app (GET v1/info shows them; relhub keys). Fetching the key from the same server at run time protects against nothing.
  2. Derive the verdict yourself from the signed manifest (manifest.versionCode > installed, manifest.minVersionCode > installed). The booleans in the response are not signed. The SDK does this.
  3. Build the download URL from your configured base URL + downloadPath, not from a URL the server sends (downloadUrl exists for humans and scripts).
  4. Always check size and sha256 after the download. On Android the system installer additionally enforces that the APK is signed by the same certificate as the installed app.

Reading (no token)

GET /healthz

200 ok, or 503 degraded plus one line per problem (a package a channel offers is missing or has the wrong size).

GET /

HTML page for people: every app × platform × channel with version, size, SHA-256, notes and a download button.

GET /v1/info (alias /v1/keys)

{"name":"release-publish","apiVersion":1,"time":"2026-10-27T06:00:00Z",
 "keys":[{"keyId":"fc7d9c7533528770","publicKey":"<base64 Ed25519>","active":true}]}

After a key rotation the retired public keys are listed with active:false.

GET /v1/apps, GET /v1/apps/{app}

{"id":"nightdesk","name":"NightDesk","description":"","createdAt":"…","platforms":[
  {"platform":"android","channels":{"stable":{"versionCode":10,"versionName":"1.3.1","size":55076236,
    "sha256":"…","minVersionCode":0,"publishedAt":"…","notes":"…"}}}]}

GET /v1/apps/{app}/check?platform=&channel=stable&versionCode=N ← the call apps make

versionCode is the installed build's code (0 if unknown). channel defaults to stable.

{"app":"nightdesk","platform":"android","channel":"stable","currentVersionCode":8,
 "updateAvailable":true,"mandatory":false,
 "manifest":{ …signed, see below… },
 "downloadPath":"v1/apps/nightdesk/android/releases/10/download",
 "downloadUrl":"https://…/release/v1/apps/…/download"}

downloadUrl is present only if the server was started with -public-url. 404 if nothing is published on that channel. Each call is counted in the statistics by installed version.

GET /v1/apps/{app}/watch?platform=&channel=&versionCode=N&wait=S

Long poll. Answers at once with the same body as check if a release newer than versionCode is offered; otherwise holds the request for up to wait seconds (default and maximum 50, below the usual 60 s proxy limit) and answers 204 if nothing happened. No connection is kept after the answer: call it again. At most 64 requests wait at once (503 beyond that).

GET /v1/apps/{app}/{platform}/latest?channel=stable

The signed manifest of the channel's current release.

GET /v1/apps/{app}/{platform}/releases?limit=50&before=N&includeYanked=1

{"releases":[Release…],"next":N} newest first. Pass next as before for the next page (0 = end). Release = {app,platform,versionCode,versionName,file,size,sha256,notes,publishedAt,yanked?,yankReason?}.

GET /v1/apps/{app}/{platform}/releases/{versionCode}

One Release.

Downloads

URL Cache-Control Use
GET /v1/apps/{app}/{platform}/releases/{code}/download public, max-age=31536000, immutable version-pinned; what apps use
GET /v1/apps/{app}/{platform}/latest/download?channel= no-cache stable link for humans/scripts; follows the channel

Both support HEAD, Range and If-Range, and send ETag: "<sha256>", X-Content-SHA256, Content-Disposition: attachment; filename="…". Resuming with If-Range: "<sha256>" restarts from zero instead of splicing two different builds if the file changed. A download that starts at byte 0 (not a resume, not a 304) counts in the statistics. Withdrawn releases answer 404.

Writing (token)

Apps (admin)

POST /v1/apps {"id","name","description"} → 201 App
PATCH /v1/apps/{app} {"name"?,"description"?} → App
POST /v1/apps/{app}/delist hide the app from the public list; anonymous app/check/watch/latest/release/download calls get 403 app_delisted
POST /v1/apps/{app}/relist undo delist

A delisted app stays fully visible to the admin token and to tokens scoped to it, which can still publish, promote and yank. Details: Admin.

Publish

POST /v1/apps/{app}/{platform}/releases, multipart/form-data. Fields first, file last (a versionCode that is too low is refused before the package is transferred):

field
versionCode required integer, higher than every earlier one on this platform
versionName required
notes optional, ≤ 8192 bytes
channel optional, default stable; an empty value uploads without offering the release anywhere
minVersionCode optional: set the channel's minimum
force true makes this release the minimum (every older app must update)
sha256 optional expected digest; the upload is rejected on mismatch
fileName optional name to store/download under (default: the uploaded name, path stripped)
file the package
curl -fsS -X POST "$BASE/v1/apps/nightdesk/android/releases" \
  -H "Authorization: Bearer $TOKEN" \
  -F versionCode=11 -F versionName=1.4.0 -F notes='fixes' -F force=false \
  -F fileName=nightdesk-1.4.0-android.apk -F file=@app-release.apk

→ 201 {"release":Release,"manifest":Manifest|null}. A client that sends Expect: 100-continue (curl does for large bodies) gets a rejected token or app before the package is sent. Allowed for the admin token and for a token scoped to this app.

Channels (admin or app token)

POST /v1/apps/{app}/{platform}/channels/{channel} {"versionCode":N,"minVersionCode"?,"force"?} promote: point the channel at an existing release (also a lower one, to roll back). A minimum above the new release is lowered to it. → Manifest
PATCH /v1/apps/{app}/{platform}/channels/{channel} {"minVersionCode":N} change the minimum. → Manifest

Yank (admin or app token)

POST /v1/apps/{app}/{platform}/releases/{code}/yank {"reason"?} and …/unyank → Release. A release that a channel currently offers is 409; promote another one first.

Statistics

GET /v1/stats?app=nightdesk (token of that app) or without app (admin):

{"apps":{"nightdesk":{"android":{"downloads":{"10":{"count":42,"last":"…"}},
                                  "checks":{"stable/8":120,"stable/10":311}}}}}

checks counts update checks by channel/installedVersionCode: which versions are out there (at most 1000 distinct keys per platform).

Tokens (admin)

POST /v1/tokens {"name","admin":true} or {"name","apps":["a","b"]} → 201 {"token":"rl_…","info":{…}} (the secret is shown once; only its hash is stored). GET /v1/tokens lists them, DELETE /v1/tokens/{id} revokes (204).

JSON-RPC

POST /v1/rpc, JSON-RPC 2.0: single calls, batches (≤ 32), notifications (no id → 204). Params are a JSON object. Same Authorization header as REST; a bad token is 401 at HTTP level. Body limit 1 MiB, so packages are uploaded over REST only.

Errors: error.code is -32700 parse, -32600 invalid request, -32601 unknown method, -32602 invalid params, or one of -32001 not_found, -32002 unauthorized, -32003 forbidden, -32004 conflict, -32005 too_large, -32006 unavailable. error.data.code always carries the API error code from the table above.

method auth params → result
server.info public – → Info
app.list public – → {apps}
app.get public {app} → App
update.check public {app,platform,channel?,versionCode} → CheckResult
update.wait public as update.check plus waitSeconds? → CheckResult, or null on timeout
release.latest public {app,platform,channel?} → Manifest
release.get public {app,platform,versionCode} → Release
release.list public {app,platform,limit?,before?,includeYanked?} → {releases,next}
app.create / app.update admin as REST → App
app.delist / app.relist admin {app} → as REST
token.create / token.list / token.revoke admin as REST
channel.promote app {app,platform,channel,versionCode,minVersionCode?,force?} → Manifest
channel.setMin app {app,platform,channel,minVersionCode} → Manifest
release.yank / release.unyank app {app,platform,versionCode,reason?} → Release
stats.get app {app?} → StatsResult
rpc.discover public – → every method with its auth level, params type and a one-line doc

"app" means: admin token, or a token scoped to that app.

curl -fsS "$BASE/v1/rpc" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"update.check","params":{"app":"nightdesk","platform":"android","versionCode":8}}'

The signed manifest

{"app":"nightdesk","platform":"android","channel":"stable","versionCode":10,"versionName":"1.3.1",
 "file":"nightdesk-1.3.1-android.apk","size":55076236,"sha256":"<64 lowercase hex>",
 "minVersionCode":0,"notes":"…","publishedAt":"2026-10-27T06:00:00Z",
 "keyId":"fc7d9c7533528770","signature":"<base64 Ed25519>"}

The signature covers these bytes, UTF-8, every line ending in \n (including the last):

relhub-release-v1
app=<app>
platform=<platform>
channel=<channel>
versionCode=<decimal>
versionName=<versionName>
file=<file>
size=<decimal>
sha256=<hex>
minVersionCode=<decimal>
publishedAt=<publishedAt>
notesSha256=<hex of SHA-256 over the notes' UTF-8 bytes; of the empty string if there are none>
  • keyId is a hint only (first 8 bytes of SHA-256 over the raw public key, hex). Verify against every pinned key.
  • Public keys are 32-byte Ed25519 keys, base64 (standard alphabet); the signature is 64 bytes, base64.
  • Field rules (reject a manifest that breaks them): app, platform, channel match the identifier patterns above; file matches ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ without ..; versionName is 1–64 characters without control characters; size is 1 … 16 GiB; 0 ≤ minVersionCode ≤ versionCode; publishedAt is RFC 3339.
  • Check that app, platform and channel are the ones you asked for: a valid signature on another app's manifest is still a valid signature.

Key rotation: relhub keys rotate -data DIR (server stopped) makes a new signing key and archives the old one. On the next start the server re-signs every channel manifest with the new key only, so an app that pins just the old public key rejects every update offer from then on. An app must therefore already pin the new public key when the switch happens. Because the new key only exists after the rotation, prepare it on a copy of the data directory, ship its public key in your apps (alongside the old one), and switch the real server later: the tested procedure is in USAGE.md.

Integration examples

Go (SDK)

keys, _ := relclient.ParseTrustedKeys("<base64 public key>")
c, _ := relclient.New("https://host/release", relclient.WithTrustedKeys(keys...))
t := relclient.Target{App: "nightdesk", Platform: "win-x64"} // Channel defaults to stable

u, err := c.Check(ctx, t, installedVersionCode)
if err == nil && u.UpdateAvailable {
    // u.Mandatory: block the UI. Resumes a leftover .part, verifies size + SHA-256,
    // then moves the file into place.
    err = c.Download(ctx, *u.Manifest, "update.zip", &relclient.DownloadOptions{
        Progress: func(done, total int64) { /* update the progress bar */ },
    })
}

// Or react the moment a release is published:
err = c.WatchLoop(ctx, t, installedVersionCode, func(u *relproto.CheckResult) error {
    notify(u.Manifest.VersionName)
    return nil // return an error to stop
})

The same client publishes: c.Publish(ctx, relclient.PublishRequest{…, Path: "app.apk"}) (needs relclient.WithToken).

pkg/relclient and pkg/relproto use only the standard library and build for Windows, Linux and (as a Go core behind a Kotlin shell) Android.

Shell

BASE=https://host/release; HAVE=8
res=$(curl -fsS "$BASE/v1/apps/nightdesk/check?platform=android&versionCode=$HAVE")
if [ "$(echo "$res" | jq .updateAvailable)" = true ]; then
  want=$(echo "$res" | jq -r .manifest.sha256)
  curl -fsS -C - -o update.apk "$BASE/$(echo "$res" | jq -r .downloadPath)"
  [ "$(sha256sum update.apk | cut -d' ' -f1)" = "$want" ] || { echo corrupt; exit 1; }
fi

(No signature check here: for scripts on a trusted network the checksum is enough; relhub check -keys … and relhub download -keys … verify the signature too.)

Kotlin / Android (sketch)

// Not compiled by this repository's tests; a minimal shape of the flow.
val base = "https://host/release"
val c = URL("$base/v1/apps/nightdesk/check?platform=android&versionCode=${BuildConfig.VERSION_CODE}")
val json = JSONObject(c.openStream().bufferedReader().use { it.readText() })
val m = json.getJSONObject("manifest")
// 1. verify m's signature over the payload above with the pinned Ed25519 key
// 2. update only if m.getLong("versionCode") > BuildConfig.VERSION_CODE
// 3. download "$base/${json.getString("downloadPath")}" with Range resume, check size + sha256
// 4. install through PackageInstaller (the system checks the signing certificate)

If the app has a Go core, call relclient from it instead and skip steps 1–3 in Kotlin.

C# / .NET

Use the Relhub.Client SDK (sdk/csharp, guide in C# SDK). It implements everything on this page, including the Ed25519 check of the signed bytes, which the .NET base class library cannot do:

using var client = new RelhubClient("https://host/release", new RelhubClientOptions().TrustKey("<base64 public key>"));
var update = await client.CheckAsync(new Target("nightdesk", "win-x64"), installedVersionCode);
if (update.UpdateAvailable)
{
    // update.Manifest is verified; the verdict was recomputed from it. Resumes, checks size + SHA-256, renames into place.
    await client.DownloadAsync(update.Manifest!, "update.zip");
}