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
- Conventions
- How an app updates itself
- Reading (no token)
- Writing (token)
- JSON-RPC
- The signed manifest
- Integration examples
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_argument400 bad id, missing field, bad JSON unauthorized401 no / invalid token ( WWW-Authenticate: Bearer)forbidden403 token may not touch this app / needs admin app_delisted403 an admin delisted the app; anonymous reads and downloads of it are refused (see Admin) not_found404 unknown app, platform, channel, release; nothing published yet conflict409 versionCode not higher; yanking a release that is still offered too_large413 package over the server limit (default 2 GiB) unavailable503 too many waiting clients; package missing on disk internal500 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 fromrelhub 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 is401. -
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:
- Pin the signing public key(s) in the app (
GET v1/infoshows them;relhub keys). Fetching the key from the same server at run time protects against nothing. - 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. - Build the download URL from your configured base URL +
downloadPath, not from a URL the server sends (downloadUrlexists for humans and scripts). - Always check
sizeandsha256after 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>
keyIdis 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,channelmatch the identifier patterns above;filematches^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$without..;versionNameis 1–64 characters without control characters;sizeis 1 … 16 GiB;0 ≤ minVersionCode ≤ versionCode;publishedAtis RFC 3339. - Check that
app,platformandchannelare 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");
}