Skip to main content

Check for catalog updates now

POST 
/catalog/refresh

Required role: admin. Only an account or token with the admin role can call this operation.

Example request
curl --request POST \
  --header "Authorization: Bearer $HOSERVA_TOKEN" \
  "https://$HOSERVA_HOST:8008/api/v1/catalog/refresh"

Runs one conditional request for the latest signed catalog from the catalog host and returns how it ended. It is an explicit user action, so it runs even when automatic refresh is off. An unchanged catalog answers 304 and downloads nothing (unchanged). A newer archive replaces the installed catalog only if its signature verifies against the compiled-in catalog key and its serial is strictly higher (updated, with the number of new and of updated templates, compared by id and revision against the catalog it replaced). Any other outcome keeps the installed catalog untouched and is failed, with a reason code and a message; a failed verification (bad_signature, not_newer, bad_archive) also raises a catalog_check_failed notification, and a network failure does not. A check that fails is still a completed check, answered 200. Calls made while a check is running share that check's request and result. A signature that does not verify makes the check fetch the archive and its signature once more before it reports bad_signature, because the two files are cached separately and can briefly disagree while a catalog is being published. Every finished check, whoever started it, is announced as a catalog event on /api/v1/events. Nothing is fetched from api.github.com.

Responses​

The check's outcome.