Skip to content

06.md

Latest commit

 

History

History
84 lines (61 loc) · 3.46 KB

06.md

File metadata and controls

84 lines (61 loc) · 3.46 KB
Raw

ORE-06

The /followers Endpoint

draft optional

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

Followers Set

The follower set of a pubkey is not well-defined in Nostr. Any pubkey can follow any other by publishing a kind-3 event, with no permission or acknowledgement required. The complete, canonical follower 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 followers of a given pubkey are.

Endpoint

POST /followers

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

Request

Field Type Required Description
pubkey string yes The target pubkey whose followers 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 followers, 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 follower set the provider considered when producing this response. This reflects the provider's indexed follower 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": 1840,
  "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, pov validation, and their associated error codes 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.