update

internal/api/handlers.go

···
 	resp.json(stats)
 }
 
+// handleGetRandomEndpoint returns a random endpoint of specified type
+func (s *Server) handleGetRandomEndpoint(w http.ResponseWriter, r *http.Request) {
+	resp := newResponse(w)
+
+	// Get required type parameter
+	endpointType := r.URL.Query().Get("type")
+	if endpointType == "" {
+		resp.error("type parameter is required", http.StatusBadRequest)
+		return
+	}
+
+	// Get optional status parameter
+	status := r.URL.Query().Get("status")
+
+	filter := &storage.EndpointFilter{
+		Type:   endpointType,
+		Status: status,
+		Random: true,
+		Limit:  1,
+		Offset: 0,
+	}
+
+	endpoints, err := s.db.GetEndpoints(r.Context(), filter)
+	if err != nil {
+		resp.error(err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	if len(endpoints) == 0 {
+		resp.error("no endpoints found matching criteria", http.StatusNotFound)
+		return
+	}
+
+	resp.json(formatEndpointResponse(endpoints[0]))
+}
+
 // ===== PDS HANDLERS =====
 
 func (s *Server) handleGetPDSList(w http.ResponseWriter, r *http.Request) {

internal/api/server.go

···
 	// Generic endpoints (keep as-is)
 	api.HandleFunc("/endpoints", s.handleGetEndpoints).Methods("GET")
 	api.HandleFunc("/endpoints/stats", s.handleGetEndpointStats).Methods("GET")
+	api.HandleFunc("/endpoints/random", s.handleGetRandomEndpoint).Methods("GET")
 
 	//PDS-specific endpoints (virtual, created via JOINs)
 	api.HandleFunc("/pds", s.handleGetPDSList).Methods("GET")

internal/storage/postgres.go

···
 		}
 	}
 
-	// NEW: Order by server_did and discovered_at to get primary endpoints
-	query += " ORDER BY COALESCE(server_did, id::text), discovered_at ASC"
+	// NEW: Choose ordering strategy
+	if filter != nil && filter.Random {
+		// For random selection, we need to wrap in a subquery
+		query = fmt.Sprintf(`
+			WITH filtered_endpoints AS (
+				%s
+			)
+			SELECT * FROM filtered_endpoints
+			ORDER BY RANDOM()
+		`, query)
+	} else {
+		// Original ordering for non-random queries
+		query += " ORDER BY COALESCE(server_did, id::text), discovered_at ASC"
+	}
 
 	if filter != nil && filter.Limit > 0 {
 		query += fmt.Sprintf(" LIMIT $%d OFFSET $%d", argIdx, argIdx+1)

internal/storage/types.go

···
 	Type            string // "pds", "labeler", etc.
 	Status          string
 	MinUserCount    int64
-	OnlyStale       bool          // NEW: Only return endpoints that need re-checking
-	RecheckInterval time.Duration // NEW: How long before an endpoint is considered stale
+	OnlyStale       bool
+	RecheckInterval time.Duration
+	Random          bool // NEW: Return results in random order
 	Limit           int
 	Offset          int
 }