{"openapi":"3.1.0","info":{"title":"Profilestr API","version":"1.0.0","description":"Free, public JSON API for Nostr profiles, follow and mute lists, relay lists and a live relay directory. No key needed and CORS is open. An MCP server with the same data is at https://profilestr.com/mcp."},"servers":[{"url":"https://profilestr.com"}],"externalDocs":{"url":"https://profilestr.com/api/docs"},"tags":[{"name":"Relays","description":"Built from the relay lists of every indexed profile: their NIP-65 list (kind 10002) where they've published one, otherwise the relay map in their follow list. Each relay is checked live (a WebSocket connect plus its NIP-11 document); results are cached for 15 minutes."},{"name":"Profiles","description":"Profile metadata and activity counts for every indexed account."},{"name":"Follow and mute lists","description":"Who a profile follows (their kind 3 list) and who they mute (kind 10000), newest saved version first. We keep earlier versions too, so you can see what changed and when."}],"paths":{"/api/relays":{"get":{"operationId":"relaysList","tags":["Relays"],"summary":"Relays ranked by how many profiles use them, with live status and NIP-11 details.","description":"Relays ranked by how many profiles use them, with live status and NIP-11 details. Also returns onlineRelays and offlineRelays: the full lists of relay URLs our background checker last saw up or down, most-used first (not affected by the filters or paging).","parameters":[{"name":"status","in":"query","required":false,"description":"all, online or offline. Default all.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"users, activeUsers or latency. Default users.","schema":{"type":"string"}},{"name":"minUsers","in":"query","required":false,"description":"Leave out relays named by fewer profiles. Default 2.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Only relays whose URL contains this text.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 500. Default 100.","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"For paging. Default 0.","schema":{"type":"string"}},{"name":"probe","in":"query","required":false,"description":"false skips the live check and returns counts only (much faster).","schema":{"type":"string"}},{"name":"statusLists","in":"query","required":false,"description":"false leaves out onlineRelays and offlineRelays.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/relays/check":{"get":{"operationId":"relaysCheck","tags":["Relays"],"summary":"Live status, latency and the NIP-11 document for a single relay, plus how many indexed profiles use it.","description":"Live status, latency and the NIP-11 document for a single relay, plus how many indexed profiles use it.","parameters":[{"name":"url","in":"query","required":true,"description":"The relay's wss:// address. Required.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/profile/{pubkey}/relays":{"get":{"operationId":"profileRelays","tags":["Relays"],"summary":"One profile's relays, with read/write markers and where the list came from (nip65 or kind3).","description":"One profile's relays, with read/write markers and where the list came from (nip65 or kind3).","parameters":[{"name":"pubkey","in":"path","required":true,"description":"npub or 64-character hex key.","schema":{"type":"string"}},{"name":"probe","in":"query","required":false,"description":"true adds online and latencyMs for each relay.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/profile/{pubkey}":{"get":{"operationId":"profile","tags":["Profiles"],"summary":"A full profile, including the combined trust score and its breakdown.","description":"A full profile, including the combined trust score and its breakdown.","parameters":[{"name":"pubkey","in":"path","required":true,"description":"npub or 64-character hex key.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/users":{"get":{"operationId":"users","tags":["Profiles"],"summary":"Search and filter profiles.","description":"Search and filter profiles.","parameters":[{"name":"name","in":"query","required":false,"description":"Partial, case-insensitive matches.","schema":{"type":"string"}},{"name":"displayName","in":"query","required":false,"description":"Partial, case-insensitive matches.","schema":{"type":"string"}},{"name":"about","in":"query","required":false,"description":"Partial, case-insensitive matches.","schema":{"type":"string"}},{"name":"nip05","in":"query","required":false,"description":"Partial, case-insensitive matches.","schema":{"type":"string"}},{"name":"pubkey","in":"query","required":false,"description":"npub or hex key.","schema":{"type":"string"}},{"name":"minFollowers","in":"query","required":false,"description":"Numeric ranges.","schema":{"type":"string"}},{"name":"maxFollowers","in":"query","required":false,"description":"Numeric ranges.","schema":{"type":"string"}},{"name":"minNotes","in":"query","required":false,"description":"Numeric ranges.","schema":{"type":"string"}},{"name":"maxNotes","in":"query","required":false,"description":"Numeric ranges.","schema":{"type":"string"}},{"name":"minZaps","in":"query","required":false,"description":"Numeric ranges.","schema":{"type":"string"}},{"name":"maxZaps","in":"query","required":false,"description":"Numeric ranges.","schema":{"type":"string"}},{"name":"sortBy","in":"query","required":false,"description":"followers, notes, zaps, created or updated. Default followers.","schema":{"type":"string"}},{"name":"sortOrder","in":"query","required":false,"description":"asc or desc. Default desc.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Limit 1 to 100, default 10.","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"Limit 1 to 100, default 10.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/users/{pubkey}":{"get":{"operationId":"usersPubkey","tags":["Profiles"],"summary":"One profile by npub or hex key.","description":"One profile by npub or hex key.","parameters":[{"name":"pubkey","in":"path","required":true,"description":"npub or 64-character hex key.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/users/random":{"get":{"operationId":"usersRandom","tags":["Profiles"],"summary":"A random selection of profiles.","description":"A random selection of profiles.","parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 50. Default 10.","schema":{"type":"string"}},{"name":"includeNpub","in":"query","required":false,"description":"true to add the npub to each profile.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/users/batch":{"post":{"operationId":"usersBatch","tags":["Profiles"],"summary":"Names, pictures and last-active times for up to 100 hex pubkeys at once.","description":"Names, pictures and last-active times for up to 100 hex pubkeys at once. Keys we haven't indexed come back as null.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pubkeys"],"properties":{"pubkeys":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/search":{"get":{"operationId":"search","tags":["Profiles"],"summary":"Autocomplete: up to 8 profiles matching a name or npub.","description":"Autocomplete: up to 8 profiles matching a name or npub.","parameters":[{"name":"q","in":"query","required":false,"description":"A name, NIP-05 or npub.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/stats":{"get":{"operationId":"stats","tags":["Profiles"],"summary":"Totals and distributions across the whole index.","description":"Totals and distributions across the whole index.","parameters":[{"name":"includeTopUsers","in":"query","required":false,"description":"Add the most-followed profiles (up to 50).","schema":{"type":"string"}},{"name":"topUsersLimit","in":"query","required":false,"description":"Add the most-followed profiles (up to 50).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/profile/{pubkey}/follows":{"get":{"operationId":"profileFollows","tags":["Follow and mute lists"],"summary":"The accounts a profile follows, with names and pictures for the ones we've indexed, plus a summary of every saved version of the list.","description":"The accounts a profile follows, with names and pictures for the ones we've indexed, plus a summary of every saved version of the list.","parameters":[{"name":"pubkey","in":"path","required":true,"description":"npub or 64-character hex key.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 1000. Default 100.","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"For paging. Default 0.","schema":{"type":"string"}},{"name":"details","in":"query","required":false,"description":"false returns keys only, without names and pictures (faster).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/profile/{pubkey}/mutes":{"get":{"operationId":"profileMutes","tags":["Follow and mute lists"],"summary":"The accounts, words and hashtags a profile mutes publicly.","description":"The accounts, words and hashtags a profile mutes publicly. Private mutes are encrypted, so we can only say whether there are any (hasPrivate).","parameters":[{"name":"pubkey","in":"path","required":true,"description":"npub or 64-character hex key.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 1000. Default 100.","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"For paging. Default 0.","schema":{"type":"string"}},{"name":"details","in":"query","required":false,"description":"false returns keys only, without names and pictures (faster).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/api/lists/{type}/{id}":{"get":{"operationId":"listVersion","tags":["Follow and mute lists"],"summary":"One saved version of a list as the raw signed Nostr event.","description":"One saved version of a list as the raw signed Nostr event. Version ids come from the versions array of the two endpoints above.","parameters":[{"name":"type","in":"path","required":true,"description":"follows or mutes.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"A version id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}}},"components":{"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}