{"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/relays/history":{"get":{"operationId":"relaysHistory","tags":["Relays"],"summary":"Uptime and latency history for a single relay from our background checker, which connects to each relay about once an hour.","description":"Uptime and latency history for a single relay from our background checker, which connects to each relay about once an hour. Returns uptime for the last 24 hours, 7, 30 and 90 days, one row per day, and every check from the last 48 hours. A relay that answers but needs payment or login counts as up.","parameters":[{"name":"url","in":"query","required":true,"description":"The relay's wss:// address. Required.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"1 to 90. How many days of daily rows to return. Default 90.","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/users":{"get":{"operationId":"relaysUsers","tags":["Relays"],"summary":"Indexed profiles that list a relay in their NIP-65 relay list (or the relay map in their follow list), with whether they read from it, write to it or both.","description":"Indexed profiles that list a relay in their NIP-65 relay list (or the relay map in their follow list), with whether they read from it, write to it or both. Rebuilt hourly.","parameters":[{"name":"url","in":"query","required":true,"description":"The relay's wss:// address. Required.","schema":{"type":"string"}},{"name":"marker","in":"query","required":false,"description":"all, read or write. Default all. read and write include profiles that use it for both.","schema":{"type":"string"}},{"name":"active","in":"query","required":false,"description":"true keeps only profiles active in the last 30 days.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"followers or recent. Default followers.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 100. Default 50.","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"For paging. Default 0.","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: Profilestr's profile check, Vertex web of trust, JEV AI's spam and bot verdict (verdict, risk 0-100, reasons) and how many of the accounts they follow were active in the last 7 days.","description":"A full profile, including the combined trust score and its breakdown: Profilestr's profile check, Vertex web of trust, JEV AI's spam and bot verdict (verdict, risk 0-100, reasons) and how many of the accounts they follow were active in the last 7 days.","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, updated (profile last refreshed) or active (last seen posting, zapping or reacting). 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/stats/history":{"get":{"operationId":"statsHistory","tags":["Profiles"],"summary":"Daily, weekly and monthly active profiles over time, from a snapshot the indexer saves once a day.","description":"Daily, weekly and monthly active profiles over time, from a snapshot the indexer saves once a day. Each row has the rolling counts as of its last day, the average daily active count across the period, the total indexed and its change since the previous period, and profile completion counts. Newest first.","parameters":[{"name":"period","in":"query","required":false,"description":"day, week or month. Weeks start on Monday (UTC). Default day.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many periods, 1 to 365. Default 30.","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"]}}}}}}}