← All NIPs

NIP-94

File Metadata

DraftEvents

Kind 1063 describes a shared file (where to download it, its type, hash, size and previews) so file-sharing apps can index and filter files on relays.

Status
In use and still allowed to change.
Kinds
Tags
  • alt
  • blurhash
  • dim
  • i
  • image
  • m
  • magnet
  • ox
  • size
  • summary
  • thumb
  • url
  • x
Last changed
Jun 13, 2026

Try it

Edit the form or the JSON: both stay in sync, the badge says whether the result is valid, and tapping any field explains it.

Examples
Valid 1 note

Not signed yet · Demo keys only. These personas' secret keys are public on purpose.

Form
Jan 1, 2025, 12:00 AM UTC

Content

A caption or description of the file.

Tags

  1. url Required

    Where to download the file.

  2. m Required

    The file's MIME type, lower case.

  3. x Required

    SHA-256 of the file.

  4. ox Recommended

    SHA-256 of the original file, before the server changed it.

  5. size Optional

    File size.

  6. dim Optional

    Image or video size.

  7. blurhash Optional

    A tiny blurred placeholder to show while loading.

  8. thumb Optional

    A thumbnail with the same aspect ratio.

  9. alt Optional

    Description for people who can't see the file.

  10. fallback Optional

    Another place to get the file if url fails. May repeat.

  11. service Optional

    Which kind of service hosts the file.

Add tag

How this NIP works

Step 1 of 5

Upload somewhere

The file itself lives on a server (NIP-96, Blossom) or a torrent. Nostr only carries the description.

In the course

No course chapter covers this NIP yet. The editor above is the quickest way in.

Used by

See also

Specification

Specification text is quoted in English from the nostr-protocol/nips repository. Our explanations and the interface are translated. Source on GitHub at commit 0046368

Read the spec369 words, quoted from the repository at commit 0046368.

The purpose of this NIP is to allow an organization and classification of shared files. So that relays can filter and organize in any way that is of interest. With that, multiple types of filesharing clients can be created. NIP-94 support is not expected to be implemented by "social" clients that deal with kind:1 notes or by longform clients that deal with kind:30023 articles.

Event format

This NIP specifies the use of the 1063 event kind, having in content a description of the file content, and a list of tags described below:

  • url the url to download the file
  • m a string indicating the data type of the file. The MIME types format must be used, and they should be lowercase.
  • x containing the SHA-256 hexencoded string of the file.
  • ox containing the SHA-256 hexencoded string of the original file, before any transformations done by the upload server
  • size (optional) size of file in bytes
  • dim (optional) size of file in pixels in the form <width>x<height>
  • magnet (optional) URI to magnet file
  • i (optional) torrent infohash
  • blurhash(optional) the blurhash to show while the file is being loaded by the client
  • thumb (optional) url of thumbnail with same aspect ratio
  • image (optional) url of preview image with same dimensions
  • summary (optional) text excerpt
  • alt (optional) description for accessibility
  • fallback (optional) zero or more fallback file sources in case url fails
  • service (optional) service type which is serving the file (eg. NIP-96)
{
  "kind": 1063,
  "tags": [
    ["url",<string with URI of file>],
    ["m", <MIME type>],
    ["x", <Hash SHA-256>],
    ["ox", <Hash SHA-256>],
    ["size", <size of file in bytes>],
    ["dim", <size of file in pixels>],
    ["magnet", <magnet URI> ],
    ["i", <torrent infohash>],
    ["blurhash", <value>],
    ["thumb", <string with thumbnail URI>, <Hash SHA-256>],
    ["image", <string with preview URI>, <Hash SHA-256>],
    ["summary", <excerpt>],
    ["alt", <description>]
  ],
  "content": "<caption>",
  // other fields...
}

Suggested use cases

  • A relay for indexing shared files. For example, to promote torrents.
  • A pinterest-like client where people can share their portfolio and inspire others.
  • A simple way to distribute configurations and software updates.