Skip to content

updatecheck API documentation

Jump to bottom
bp2008 edited this page Jul 5, 2026 · 4 revisions

updatecheck JSON API — Proposal & Documentation

Status: Proposed (not yet implemented in Blue Iris)

This page documents a proposed addition to the Blue Iris JSON API: an administrator-only updatecheck command that returns the information Blue Iris already collects when it checks for updates, in a structured JSON form.

UI3 already implements the client side of this feature since Ui3-332. A "Check for Updates" button in Server Control opens a "Blue Iris News and Updates" dialog modeled on the one in the Blue Iris console. Until Blue Iris implements updatecheck, that dialog shows a limited fallback based on the newversion string already present in the login response, along with a link to this page. If/when Blue Iris begins responding to updatecheck API requests, the full dialog lights up automatically with no further UI3 update required.

Summary

Property Value
Command updatecheck
Access level Administrator only
Method Standard JSON API POST to /json
Side effects May trigger an update check against Blue Iris's backend (throttled/cached — see below)

Throttling

updatecheck may be called whenever an administrator opens or refreshes the dialog, so Blue Iris should internally throttle requests to its own backend to limit server load and cost. A cache of roughly one real backend request per minute is suggested; return the most recent cached result for calls in between. The throttling should be transparent to the caller — UI3 does not need to know whether a response is fresh or cached.

Relationship to the existing newversion field

The existing newversion string in the login/status response should remain unchanged. It is a passive "an update is available" indicator that does not require explicit polling, and UI3 still uses it (including as the fallback when updatecheck is unsupported). updatecheck is the richer, on-demand counterpart used when the user actively opens the updates dialog.

Request

A standard JSON API request. Only the session and command are required:

{
  "cmd": "updatecheck",
  "session": "<session id>"
}

If the session is not an administrator session, respond as Blue Iris normally does for commands that require elevated privileges.

Response

On success, return the standard envelope with the update information in data:

{
  "result": "success",
  "session": "<session id>",
  "data": {
    "news": "…",
    "maintenance_expire": 1893456000000,
    "maintenance_purchase_link": "https://blueirissoftware.com/#support",
    "changelog_url": "https://blueirissoftware.com/changelog6.pdf",
    "newversions": [ … ]
  }
}

data fields

Field Type Required Description
news string no Free-form news/announcement text shown at the top of the dialog. Newlines (\n) are preserved. Omit or leave empty to hide the News section.
maintenance_expire number no Support & maintenance expiration, as milliseconds since the Unix epoch (UTC). Used to warn before installing a version released after this date. Omit if unknown/not applicable.
maintenance_purchase_link string no URL where the user can read more about renewing support & maintenance. If this URL is omitted, no guidance will be given to the user for how to renew.
changelog_url string no URL of the full changelog. Defaults to https://blueirissoftware.com/changelog6.pdf if omitted.
newversions array yes The list of available versions (see below). May be given in any order; UI3 sorts it.

newversions[] entry fields

Field Type Required Description
version string yes Dotted version number, e.g. "6.0.8.6".
date number no Release date as milliseconds since the Unix epoch (UTC). Displayed next to the version and compared against maintenance_expire.
stable boolean no true marks a version as a "critical or highly-stable" update. The newest stable entry becomes the "Install latest critical or highly-stable update" option. Defaults to false.
notes string no Release notes for this version. Newlines (\n) are preserved and shown in a notes box beneath the option.

Example success response

{
  "result": "success",
  "session": "abc123",
  "data": {
    "news": "Blue Iris 6 is here! Visit blueirissoftware.com to learn about new features and pricing.",
    "maintenance_expire": 1893456000000,
    "maintenance_purchase_link": "https://blueirissoftware.com/#support",
    "changelog_url": "https://blueirissoftware.com/changelog6.pdf",
    "newversions": [
      {
        "version": "6.0.8.6",
        "date": 1782777600000,
        "stable": false,
        "notes": "Smoother timeline playback for UI3 and app\nOther minor enhancements and bug fixes"
      },
      {
        "version": "6.0.8.4",
        "date": 1782172800000,
        "stable": true,
        "notes": "Fixes for 6.0.7.7 A/V sync issues\nSmoother timeline playback for UI3 and app\nOther minor enhancements and bug fixes"
      },
      {
        "version": "6.0.8.3",
        "date": 1782086400000
      }
    ]
  }
}

How UI3 interprets the response

Given a successful response, UI3 builds the dialog as follows:

  1. Sort newversions in descending version order.
  2. Latest = the highest version overall → "Install latest update available".
  3. Latest stable = the highest version with "stable": true → "Install latest critical or highly-stable update". Omitted if no entry is marked stable.
  4. Current = the entry whose version matches the running Blue Iris version (from the login response). Shown as "Remain with your current version".
  5. Previous = every remaining version, offered in a dropdown as "Another available previous update".
  6. License-renewal warning: for any offered version whose date is later than maintenance_expire, UI3 shows a ⚠ marker and, before installing, warns that the version may fail to activate without renewing support & maintenance (linking to maintenance_purchase_link).
  7. Status line: compares the latest version to the running version to show "An update is available." or "Blue Iris is up-to-date."
  8. Install reuses the existing update mechanism (the update field of the status command), so no new install API is required.

Selecting an option and clicking OK installs that version (with confirmation); Cancel closes the dialog.

Backward compatibility & failure handling

UI3 does not assume any particular Blue Iris version. It decides what to show from the response:

  • result: "success" → render the full dialog from data (even an empty newversions array is handled gracefully).
  • result: "fail" with data.reason == "invalid session" → re-authenticate, then retry.
  • Any other result: "fail" (the expected response from a Blue Iris version that does not recognize the command) → render the limited fallback dialog and a link back to this page.

Because of this, implementing updatecheck is purely additive: older Blue Iris versions keep working with the fallback UI, and no UI3 release is required to enable the full dialog once Blue Iris starts responding to the command.

This page documents the client-side contract implemented in UI3-332.

Clone this wiki locally