Skip to content

04.md

Latest commit

 

History

History
104 lines (78 loc) · 4.36 KB

04.md

File metadata and controls

104 lines (78 loc) · 4.36 KB
Raw

ORE-04

The /recommend/pubkeys Endpoint

draft optional

This document defines the /recommend/pubkeys endpoint, which returns a ranked list of pubkeys that a provider recommends. The provider selects and ranks candidates entirely on its own, making it useful for discovery. Algorithms on this endpoint MAY require a topic to narrow recommendations to a specific subject area.

Capability Document

Algorithms on this endpoint MAY declare "topic": true in their Algorithm Object to indicate that they require a topic string in every request. The rules for topic in the capability document follow the same pattern as pov, as defined in ORE-01.

[
  {
    "id": "top-experts",
    "description": "Top experts on a given topic.",
    "topic": true
  },
  {
    "id": "for-you",
    "description": "Personalised recommendations based on your social graph.",
    "pov": true
  }
]

Topic

The topic field is intended to be a free-form string, typically derived from direct user input. Providers that support it SHOULD interpret it as broadly and generously as possible, since users may phrase the same subject in different ways.

Providers that offer recommendations in specific, well-known categories SHOULD expose those as distinct named algorithms without a topic parameter, rather than constraining a free-form field to a fixed taxonomy. For example, a provider offering curated lists for bitcoin, art, and music SHOULD define recommendations-bitcoin, recommendations-art, and recommendations-music as separate algorithms. The topic parameter is for open-ended queries that cannot be anticipated in advance.

Endpoint

POST /recommend/pubkeys

Returns up to limit results selected and ranked by the provider according to the requested algorithm.

Request

Field Type Required Description
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.
topic string no A topic to narrow recommendations to. MUST be provided if the requested algorithm requires it, as declared in the capability document. Clients SHOULD NOT send a topic longer than 512 characters.
limit integer no The maximum number of results to return. MUST be a positive integer. If omitted, the provider MUST use its own default. Clients SHOULD NOT request more than 1000.

Example Request

{
  "algorithm": "top-experts",
  "pov": "a3f69...",
  "topic": "bitcoin",
  "limit": 20
}

Response

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 at most limit entries.
ttl integer no A hint indicating how many seconds the returned ranks 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.87 },
    { "pubkey": "a3f9c...", "rank": 0.74 }
  ],
  "ttl": 7200
}

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 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.
422 The requested algorithm requires a topic but none was provided.
422 The topic value exceeds the maximum allowed length.
422 The topic value is not recognised by the provider.