Skip to content

Feed format ​

This page is the reference for the snapshot feed: a JSON array served over HTTPS, one entry per current snapshot. To publish one, follow Contribute snapshots. The registry side is described in Registry file.

Feed fields ​

Fill all six fields below for each entry. A missing field is shown as "N/A" on SnapsVault, except where the table names a fallback. A value of null or "" counts as absent, and unknown keys are ignored. A present field with an invalid value skips that entry.

FieldWhat to provideRuleWhen absent
urlHTTPS download URL of the snapshot fileURL rules, no fragment. Alias download_url.The entry is skipped
filenameFile name of the snapshot file^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$, no ..Last path segment of url
sizeSize of the snapshot file with a unit, such as 38Gb or 4.4GBA number with a unit (B, or K, M, G, T, P with optional B or iB), case-insensitive, so 38Gb and 38GB both mean 38 gigabytes. At most 24 characters.Shown as "N/A"; the API returns "0GB"
creation_dateWhen the snapshot was madeISO 8601 with Z or an offset, a real date between 2019-01-01 and one day from now. Alias time.Time of the sync
latest_block_heightBlock height of the snapshotSafe integer or a string of 1 to 15 digits. Aliases block_height, height. See the height rule.Counts as 0
sha256sumSHA256 of the snapshot file64 hex characters, stored lower case. Alias checksum.sha256. If the server already writes a .sha256 file, use only its first 64 characters (the hash), not the whole line with the file name.No checksum is shown
Size units

A bare number is read as GB, and a digit string without a unit is shown without one. Never publish bytes: the check fails a bare value above 100000. Sorting by size across units is approximate.

Also accepted in a feed ​

type, period and tx_index belong in the registry file, which explains each of them. The registry values win, and the feed values are used only when the registry file leaves them out.

FieldRule
typeMatches ^[A-Za-z0-9._-]{1,32}$
periodMatches ^[A-Za-z0-9._-]{1,32}$
tx_indexA boolean, or "true" or "false"

When neither file sets the type, the type of the newest entry is used.

What the check requires ​

The registry check fails an entry only when it has no valid url, when a present field has an invalid value, or when it breaks the height rule. A missing size or sha256sum gives a warning. Everything else missing is shown as "N/A" or replaced by the fallback in the table. Fill all six fields so every snapshot shows its size, date, height and checksum.

Height rule ​

Height above 0

latest_block_height must be above 0 for every entry, unless the effective type is exactly archive (lower case), an archive that starts at genesis. A missing height counts as 0. The effective type is the type in the registry file, else the type of the newest entry in the feed (by creation_date), else the type of the entry itself. An entry that breaks the rule is skipped.

How fields show on SnapsVault ​

  • SHA256 is shown next to the snapshot.
  • Type applies to every entry of a feed, so one feed carries one type. An entry whose own type differs from the registry type gets a warning from the check.
  • Period values in the 4h, 1d and 1w style are parsed for "next update".
  • Size is shown as published.
  • Reachability. The check sends a HEAD request to the url of the newest entry and warns when the snapshot file does not answer with a success status.

Feed limits ​

LimitValue
TransportHTTPS only, redirects refused
Timeout10 seconds
Body sizeAt most 1 MiB, checked on Content-Length and while reading
Top levelJSON array with at least one entry
Entries kept500 newest
How a snapshot is identified

A snapshot is identified by network, chain ID, type, contributor and height. A snapshot without a height (an archive, stored as height 0) is identified by its download URL instead, so each snapshot file is its own snapshot. A feed that repeats the same height still updates that one snapshot in place, so publish a new height for each snapshot to build history. Snapshots that leave the feed move to the history, which the API returns through /api/snapshots/historical.

URL rules ​

These apply to feed URLs, download URLs and profile links.

RuleDetail
Length and charactersAt most 2048 characters from A-Z a-z 0-9 . _ ~ : / ? & = % + , @ - (profile links may also contain #)
SchemeStarts with lowercase https://
Host charactersOnly letters, digits, dots and hyphens: no user, password, port or percent-encoding
Host nameA public DNS name with at least two labels and an alphabetic top-level label. IP addresses, localhost and names ending in .local, .localhost, .internal, .localdomain, .lan or .home.arpa are rejected.

Next steps ​

SnapsVault, Open Snapshot Marketplace