HeadDB

The modern build of the fork uses a complete snapshot for startup or recovery, then requests only catalog changes after its saved revision. The primary URLs are:

https://headdb.net/api/v1/catalog/snapshot
https://headdb.net/api/v1/catalog/changes

In plugins/HeadDB/config.yml, set:

database:
  sourceUrl: "https://headdb.net/api/v1/catalog/snapshot"
  syncUrl: "https://headdb.net/api/v1/catalog/changes"
  syncIntervalMinutes: 15
  fallbackSourceUrls:
    - "https://headdb.net/api/v1/legacy/heads.json"
    - "https://raw.githubusercontent.com/BitworksMC/HeadDB/master/heads.json"

The modern plugin stores a last-known-good catalog and its revision in its data folder. On each sync it applies complete upsert records and explicit removals, builds new indexes, then atomically publishes the result. A failed request never replaces the last valid catalog.

The modern feed includes Mojang textures and heads created from direct skin uploads. Older plugin builds can continue using https://headdb.net/api/v1/legacy/heads.json; that compatibility feed contains Mojang-backed textures only and refreshes as one full download.

After changing the configuration, restart HeadDB so it performs a fresh download. Leave updater: true to enable periodic synchronization.

Plugin setup