Push-mode fleets

Pull mode (GET /u/…) assumes each device checks in on its own. Plenty of fleets don't work that way: routers, firmware, kiosks and agents behind a management plane, where your orchestrator talks to the devices and pushes updates to them. In push mode the orchestrator speaks to Relayer on the devices' behalf - Relayer still owns the decisions (rollout cohorts, channel policy, rollback), your system owns the transport.

Both endpoints are API-key authenticated and accept up to 500 devices per call, so a whole wave costs one request against the rate limit instead of one per device.

Report fleet state

POST /api/v1/fleet/report - a heartbeat on the devices' behalf. Devices appear in the fleet dashboard, adoption charts and the live feed exactly as if they had checked in themselves.

curl -X POST https://www.relayercli.com/api/v1/fleet/report \
  -H "Authorization: Bearer rl_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "YOUR_APP_REF",
    "devices": [
      {
        "deviceId": "router-0042",
        "version": "1.4.0",
        "platform": "linux",
        "arch": "aarch64",
        "labels": { "customerRef": "acme-42", "siteRef": "blr-dc1" }
      }
    ]
  }'

Devices are upserted on (app, deviceId) - report as often as you like. channel defaults to stable.

Labels

labels are key/values (max 16 per device, keys ≤ 64 chars, values ≤ 256) stored on the device row and echoed in the devices table and API responses. Use them to correlate Relayer's records with your own tenant hierarchy (customerRef, siteRef, routerName, …). A report without labels never clears labels a previous report attached; sending labels replaces them.

Labels also drive release targeting: a release can be restricted to devices whose labels match (set per release on the Releases tab). Devices whose labels don't match a targeted release fall through to the newest untargeted release below it. Apart from targeting rules you define, Relayer never interprets label contents.

Plan an update wave

POST /api/v1/fleet/decisions - hand Relayer the fleet's current state, get back one decision per device. This runs the exact same logic as GET /u/ (same code, not a copy): version comparison, staged-rollout bucketing with fall-through, artifact matching and channel policy.

curl -X POST https://www.relayercli.com/api/v1/fleet/decisions \
  -H "Authorization: Bearer rl_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "YOUR_APP_REF",
    "channel": "stable",
    "devices": [
      { "deviceId": "router-0042", "version": "1.4.0", "platform": "linux", "arch": "aarch64" },
      { "deviceId": "router-0043", "version": "1.5.0", "platform": "linux", "arch": "aarch64" }
    ]
  }'

{
  "app": "YOUR_APP_REF",
  "channel": "stable",
  "decisions": [
    {
      "deviceId": "router-0042",
      "update": {
        "version": "1.5.0",
        "url": "https://your-storage/agent-1.5.0-linux-aarch64.bin",
        "sha512": "…",
        "updateMode": "recommended",
        "notes": "## 1.5.0 …",
        "pub_date": "2026-07-01T10:00:00.000Z"
      }
    },
    { "deviceId": "router-0043", "update": null }
  ],
  "updatesOffered": 1
}

update: null means up to date, outside the current rollout cohort, excluded by release targeting, or no artifact for that platform/arch - the same cases where /u/ answers 204. Your orchestrator pushes the artifact to each device with a non-null decision, then confirms with a follow-up report once the device is on the new version.

Devices may also carry inline labels in a decisions call; they merge key-by-key over labels stored by earlier reports (inline wins) and feed release targeting. If a device sits on a rolled-back version, its decision points at the newest published release below it with "allowDowngrade": true - push it like any other update.

Dry runs

Add "dryRun": true to plan a wave without writing anything - no device upserts, no check-ins. Useful for previewing how many devices a rollout percentage would reach before you commit.

Semantics worth knowing

Staged rollouts behave identically in both modes: a device outside a 25% cohort falls through to the newest fully-rolled-out release, and cohort membership is sticky (sha256(deviceId:releaseId) % 100). Channel minVersion policy flags decisions updateMode: "required" for devices below the minimum. Rolled-back releases are never offered - devices already on one get the newest published release below it as a downgrade. Mixing modes is fine - the same device can check in via /u/ today and be reported by an orchestrator tomorrow; it's one row keyed by (app, deviceId).

Errors