← All NIPs

NIP-50

Search Capability

DraftRelay messagesRelay

Adds a search field to REQ filters so clients can ask relays for full-text results, such as "best nostr apps". Relays rank results by relevance instead of date and may support extra key:value options like language:en.

Status
In use and still allowed to change.
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

Form
REQ Client → relay

  1. Any id the client picks for this subscription.

  2. A NIP-01 filter plus search: a human-readable query. Several filters may be sent; each can have its own search.

A normal subscription whose filter has a search string. Other filter fields (kinds, authors, limit…) narrow the results as usual.

How this NIP works

Step 1 of 4

Put the query in search

The search field holds free text. Relays match it against content and, where it makes sense for the kind, other fields too.

In the course

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

Builds on

Extends

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 spec406 words, quoted from the repository at commit 0046368.

Abstract

Many Nostr use cases require some form of general search feature, in addition to structured queries by tags or ids. Specifics of the search algorithms will differ between event kinds, this NIP only describes a general extensible framework for performing such queries.

search filter field

A new search field is introduced for REQ messages from clients:

{
  // other fields on filter object...
  "search": <string>
}

search field is a string describing a query in a human-readable form, i.e. "best nostr apps". Relays SHOULD interpret the query to the best of their ability and return events that match it. Relays SHOULD perform matching against content event field, and MAY perform matching against other fields if that makes sense in the context of a specific kind.

Results SHOULD be returned in descending order by quality of search result (as defined by the implementation), not by the usual .created_at. The limit filter SHOULD be applied after sorting by matching score. A query string may contain key:value pairs (two words separated by colon), these are extensions, relays SHOULD ignore extensions they don't support.

Clients may specify several search filters, i.e. ["REQ", "", { "search": "orange" }, { "kinds": [1, 2], "search": "purple" }]. Clients may include kinds, ids and other filter field to restrict the search results to particular event kinds.

Clients SHOULD use the supported_nips field to learn if a relay supports search filter. Clients MAY send search filter queries to any relay, if they are prepared to filter out extraneous responses from relays that do not support this NIP.

Clients SHOULD query several relays supporting this NIP to compensate for potentially different implementation details between relays.

Clients MAY verify that events returned by a relay match the specified query in a way that suits the client's use case, and MAY stop querying relays that have low precision.

Relays SHOULD exclude spam from search results by default if they support some form of spam filtering.

Extensions

Relay MAY support these extensions:

  • include:spam - turn off spam filtering, if it was enabled by default
  • domain:<domain> - include only events from users whose valid nip05 domain matches the domain
  • language:<two letter ISO 639-1 language code> - include only events of a specified language
  • sentiment:<negative/neutral/positive> - include only events of a specific sentiment
  • nsfw:<true/false> - include or exclude nsfw events (default: true)