Skip to content

07.md

Latest commit

 

History

History
84 lines (61 loc) · 3.39 KB

07.md

File metadata and controls

84 lines (61 loc) · 3.39 KB
Raw

ORE-07

The /muters Endpoint

draft optional

This document defines the /muters endpoint, which returns the top-ranked muters of a given Nostr pubkey.

Muter Set

The muter set of a pubkey is not well-defined in Nostr. Any pubkey can mute any other by publishing a kind-10000 event, with no permission or acknowledgement required. The complete, canonical muter set of a pubkey is therefore impossible to determine.

However, the top-ranked portion of that set is both knowable and useful. Providers index the pubkeys they consider reputable and meaningful, and within that indexed set they can determine, with reasonable confidence, who the most relevant muters of a given pubkey are.

Endpoint

POST /muters

Returns up to limit muters of the given pubkey, sorted by rank in descending order.

Request

Field Type Required Description
pubkey string yes The target pubkey whose muters are to be returned. MUST follow the format defined in ORE-00.
algorithm string no The algorithm to use. If omitted, the provider MUST use the default algorithm for this endpoint as defined in ORE-01.
pov string no A point-of-view pubkey for personalised algorithms. MUST be provided if the requested algorithm requires it, as declared in the capability document.
limit integer no The maximum number of results to return. MUST be a positive integer. If omitted, the provider MUST use a sensible default. Clients SHOULD NOT request more than 1000.

Example Request

{
  "pubkey": "a3f9c...",
  "algorithm": "pagerank",
  "limit": 50
}

Response

Field Type Required Description
results array of objects yes An array of result objects representing muters, sorted by rank in descending order. Each object MUST include pubkey (string) and rank (number). Contains at most limit entries.
total integer no The cardinality of the muter set the provider considered when producing this response. This reflects the provider's indexed muter set for the given pubkey. Clients MAY display this value to give users a sense of scale.
ttl integer no A hint indicating how many seconds the returned results are expected to remain valid. Clients MAY cache the result for this duration. Clients MUST treat this value as a hint, not a guarantee.

Example Response

{
  "results": [
    { "pubkey": "b7e2d...", "rank": 0.91 },
    { "pubkey": "cc481...", "rank": 0.76 },
    { "pubkey": "f1a3b...", "rank": 0.54 }
  ],
  "total": 42,
  "ttl": 3600
}

Success Codes

Status Description
200 The result is ready and the response body contains the result.
202 The result is not yet available. Clients MUST retry the identical request after the number of seconds indicated by the Retry-After response header.

Error Codes

Algorithm selection and pov validation follow the rules defined in ORE-01.

Status Reason
400 The request body is malformed or not valid JSON.
422 The pubkey field is missing or invalid.
422 The limit value is not a positive integer.
422 The limit value exceeds the maximum supported by the provider.
422 The requested algorithm is not supported by this endpoint.
422 The requested algorithm requires a pov but none was provided.