Profilestr

ReportsAPI Documentation

Overview

The Nostr Profiles API provides access to user profile data from the Nostr network. All endpoints return JSON responses and support CORS for cross-origin requests.

Base URL

https://profilestr.com/api

Rate Limiting

100 requests per minute per IP

Response Format

All responses are JSON

CORS

Enabled for all origins

Authentication

Currently, the API is public and does not require authentication. All endpoints are accessible without API keys.

Future Plans

API key authentication may be added in the future for higher rate limits and additional features.

Endpoints

GET/api/users

Retrieve a list of users with optional filtering and pagination.

Query Parameters

pubkeyFilter by public key (partial match)
nameFilter by name (partial match)
displayNameFilter by display name (partial match)
limitNumber of results (1-100, default: 10)
offsetNumber of results to skip (default: 0)

Example Request

GET /api/users?name=alice&limit=5&offset=10
GET/api/users/:pubkey

Retrieve a specific user by their public key (hex or npub format).

Path Parameters

pubkeyUser's public key (hex or npub format)

Example Request

GET /api/users/npub1abc123...
GET/api/users/random

Retrieve a random selection of users from the database. Perfect for discovery and showcasing diverse profiles.

Query Parameters

limitNumber of random users to return (1-50, default: 10)
includeNpubInclude npub format in response (true/false, default: false)

Example Request

GET /api/users/random?limit=10&includeNpub=true
GET/api/users/:displayName

Search for users by their display name. Perfect for autocomplete functionality with intelligent matching and relevance scoring.

Path Parameters

displayNameDisplay name or name to search for

Query Parameters

limitNumber of results to return (1-50, default: 10)
exactExact match only (true/false, default: false)
includeNpubInclude npub format in response (true/false, default: true)

Example Requests

GET /api/users/fiatjafGET /api/users/jack?limit=5&exact=true

Data Types

User Object

id

string (UUID)

pubkey

string (hex)

name

string | null

displayName

string | null

about

string | null

picture

string | null

nip05

string | null

lud16

string | null

followersCount

number

followsCount

number

noteCount

number

zapCount

number

Interactive API Testers

Test Random Users API

GET/api/users/random

Get a random selection of users from the database

Parameters

Number of users to return (1-50)

Include npub format in response

https://profilestr.com/api/users/random

Test Display Name Search API

GET/api/users/fiatjaf

Search for users by display name with autocomplete functionality

Parameters

Number of results to return (1-50)

Exact match only

Include npub format in response

https://profilestr.com/api/users/fiatjaf

Note: Change "fiatjaf" in the endpoint URL above to test different display names.

Examples

Get Random Users

curl "https://profilestr.com/api/users/random?limit=10&includeNpub=true"

Returns 10 random users with npub format included

Search Users by Display Name

curl "https://profilestr.com/api/users/fiatjaf?limit=5"

Search for users with "fiatjaf" in their display name or name, perfect for autocomplete

Get Top Users

curl "https://profilestr.com/api/users?minFollowers=100&limit=10&sortBy=followers&sortOrder=desc"

Returns the top 10 users with at least 100 followers, sorted by follower count

Search Users by Name

curl "https://profilestr.com/api/users?name=alice&limit=5"

Search for users with "alice" in their name

Search Users by Multiple Criteria

curl "https://profilestr.com/api/users?name=alice&displayName=developer&minFollowers=50"

Search for users with "alice" in name, "developer" in display name, and at least 50 followers

Get Specific User

curl "https://profilestr.com/api/users/npub1abc123..."

Get a specific user by their npub

Error Handling

400 Bad Request

Invalid query parameters or malformed request

{ "error": "Invalid query parameters" }

404 Not Found

User not found or endpoint doesn't exist

{ "error": "User not found" }

500 Internal Server Error

Server error or database connection issue

{ "error": "Internal server error" }