Skip to content

03.md

Latest commit

 

History

History
89 lines (64 loc) · 3.46 KB

03.md

File metadata and controls

89 lines (64 loc) · 3.46 KB
Raw

ORE-03

The /rank/pubkeys Endpoint

draft mandatory

This document defines the /rank/pubkeys endpoint, which accepts a set of pubkeys and returns them ranked by a provider algorithm. It is the batch counterpart to /stats/pubkey, returning a ranked list of pubkeys rather than a single pubkey's statistics.

Endpoint

POST /rank/pubkeys

Accepts a set of pubkeys and returns up to limit results sorted by rank in descending order, according to the requested algorithm.

Request

Field Type Required Description
pubkeys array of strings yes The pubkeys to rank. MUST contain at least one element.
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 pubkey for personalized 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, defaults to the number of pubkeys in the request. If greater than the number of pubkeys in the request, it is silently clamped to that number.

Example Request

{
  "pubkeys": [
    "a3f9c...",
    "b7e2d...",
    "cc481..."
  ],
  "algorithm": "pagerank",
  "limit": 2
}

Response

The response is a JSON object with the following fields:

Field Type Required Description
results array of objects yes An array of result objects sorted by rank in descending order. Each object MUST include pubkey (string) and rank (number). Contains exactly limit entries, after clamping as described above.
ttl integer no A hint indicating how many seconds the returned ranks are expected to remain valid. Reflects the provider's indexing cadence and the stability of the requested algorithm. Clients MAY cache the ranks for this duration and avoid redundant requests. Clients MUST treat this value as a hint, not a guarantee.

Unknown pubkeys

Providers MUST return a rank for every requested pubkey, including pubkeys they have never encountered. The rank assigned to an unknown pubkey is at the provider's discretion and MUST reflect the semantics of the requested algorithm.

Request size

Clients SHOULD NOT send more than 1000 pubkeys in a single request. Providers MAY enforce their own limit and SHOULD respond with 413 Payload Too Large if the request exceeds it.

Example Response

{
  "results": [
    { "pubkey": "b7e2d...", "rank": 950 },
    { "pubkey": "a3f9c...", "rank": 312 }
  ],
  "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.
413 The number of pubkeys in the request exceeds the provider's limit.
422 The pubkeys array is empty.
422 The limit value is not a positive integer.
422 The requested algorithm is not supported by this endpoint.
422 The requested algorithm requires a pov but none was provided.