Skip to content

02.md

Latest commit

 

History

History
89 lines (67 loc) · 3.2 KB

02.md

File metadata and controls

89 lines (67 loc) · 3.2 KB
Raw

ORE-02

The /stats/pubkey Endpoint

draft mandatory

This document defines the /stats/pubkey endpoint, which returns a rank and a set of statistics for a single Nostr pubkey.

Endpoint

POST /stats/pubkey

Returns a rank and statistics for the given pubkey according to the requested algorithm.

Request

Field Type Required Description
pubkey string yes The pubkey to retrieve statistics for. 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.

Example Request

{
  "pubkey": "a3f9c...",
  "algorithm": "wot-rank",
  "pov": "b7e2d..."
}

Response

The response is a JSON object. pubkey and rank are always present. All other fields are optional and MAY be omitted by the provider depending on available data.

Field Type Required Description
pubkey string yes The pubkey that was queried, as provided in the request.
rank number yes The rank assigned to this identity by the requested algorithm. Higher values are always better. The scale and range are defined by the algorithm.
follows integer no Number of pubkeys this identity follows.
followers integer no Number of pubkeys that follow this identity.
mutes integer no Number of pubkeys this identity has muted.
muters integer no Number of pubkeys that have muted this identity.
reports integer no Number of reports received by this identity.
reporters integer no Number of pubkeys that have reported this identity.
first_seen_at integer no Unix timestamp of the first activity by this identity seen by the provider.
ttl integer no A hint indicating how many seconds the response is expected to remain valid. Clients MAY cache the result for this duration. Clients MUST treat this value as a hint, not a guarantee.

Providers MAY include additional numeric fields beyond those listed below. Clients MUST ignore unrecognised fields.

Example Response

{
  "pubkey": "a3f9c...",
  "rank": 0.91,
  "follows": 320,
  "followers": 1400,
  "mutes": 5,
  "muters": 12,
  "reports": 0,
  "reporters": 0,
  "first_seen_at": 1673000000,
  "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 requested algorithm is not supported by this endpoint.
422 The requested algorithm requires a pov but none was provided.