Skip to content

05.md

Latest commit

 

History

History
78 lines (57 loc) · 2.76 KB

05.md

File metadata and controls

78 lines (57 loc) · 2.76 KB
Raw

ORE-05

The /search/pubkeys Endpoint

draft optional

This document defines the /search/pubkeys endpoint, which returns a ranked list of pubkeys whose kind:0 profile event matches a free-form query string.

Endpoint

POST /search/pubkeys

Returns up to limit results matching the given query, sorted by rank in descending order.

Request

Field Type Required Description
query string yes A free-form search string. MUST NOT be empty. Clients SHOULD NOT send a query longer than 512 characters.
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 its own default. Clients SHOULD NOT request more than 1000.

Example Request

{
  "query": "jack",
  "algorithm": "semantic-v1",
  "limit": 20
}

Response

Field Type Required Description
results array of objects yes An array of result objects matching the query, 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 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.95 },
    { "pubkey": "cc481...", "rank": 0.88 },
    { "pubkey": "a3f9c...", "rank": 0.76 }
  ],
  "ttl": 300
}

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 query field is missing or empty.
422 The query value exceeds the maximum allowed length.
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.