Search and Discovery API
Relevant source files
The following files were used as context for generating this wiki page:
- packages/registry/src/routes/search.ts
- packages/registry/src/routes/ai-search.ts
- packages/registry/src/services/ai-search.ts
- packages/registry/src/search/postgres.ts
- packages/webapp/src/app/blog/introducing-use-cases/page.tsx
- packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
- packages/webapp/src/app/blog/format-specifications-guide/page.tsx
- packages/converters/src/tests/from-agents-md.test.ts
- packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx
The Search and Discovery API is a core component of the PRPM platform, designed to help users find relevant AI prompt packages from a registry of over 7,500 items. It addresses the challenge of discoverability in a large and growing ecosystem by providing multiple search modalities, including traditional keyword-based search, AI-powered semantic search, and a curated "Use Case" browsing experience. This system enables users to find packages based on their intended function rather than just metadata.
The API is not just a search interface but also a gateway to PRPM's universal compatibility features. It allows users to find a package in one format and install it for use in a different AI IDE, handling the conversion automatically. This is central to PRPM's mission to "install once, use anywhere" across a fragmented landscape of AI coding tools.
Sources: packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx, packages/webapp/src/app/blog/introducing-use-cases/page.tsx
API Overview
The search and discovery functionality is exposed through two primary API endpoints: one for traditional keyword search and another for AI-powered semantic search. Both are designed to help users navigate the extensive package registry.
Search Flow
The following diagram illustrates the high-level flow for both search types.
This diagram shows how a user's search query is routed to either the traditional or AI search backend, which then returns a ranked list of packages.
Sources: packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx, packages/registry/src/routes/search.ts, packages/registry/src/routes/ai-search.ts
Traditional Keyword Search
This is the standard search functionality, accessible via the /search endpoint. It allows users to find packages using keywords, with support for filtering and pagination.
Sources: packages/registry/src/routes/search.ts, packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx
API Endpoint: GET /search
This endpoint performs a full-text search against the PostgreSQL database. It's optimized for queries where the user knows specific terms they are looking for.
Sources: packages/registry/src/routes/search.ts, packages/registry/src/search/postgres.ts
Query Parameters
| Parameter | Type | Description |
|---|---|---|
q | string | The search query string. |
page | number | The page number for pagination. |
format | string | Filters results by a specific package format (e.g., cursor, claude-skill). |
subtype | string | Filters results by a package subtype (e.g., agent, tool). |
tags | string | A comma-separated list of tags to filter by. |
author | string | Filters results by the package author. |
useCase | string | Filters results by a specific use case tag. |
Sources: packages/registry/src/routes/search.ts, packages/webapp/src/app/blog/introducing-use-cases/page.tsx
AI Semantic Search
For more complex or intent-based queries, PRPM provides an AI-powered semantic search. This allows users to describe what they want to achieve in natural language, and the system finds relevant packages even if the keywords don't match exactly.
Sources: packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx, packages/registry/src/routes/ai-search.ts
API Endpoint: POST /ai-search
This endpoint takes a natural language query, generates an embedding for it, and performs a vector search against the package embeddings stored in the database.
AI Search Sequence Diagram
The diagram below shows the sequence of operations for an AI search request.
This illustrates the interaction between the client, the API server, the AI search service, and the database to fulfill a semantic search query.
Sources: packages/registry/src/routes/ai-search.ts, packages/registry/src/services/ai-search.ts, packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx
Use Case Discovery
To further improve discoverability, PRPM introduced "Use Cases," which organize packages by the problems they solve rather than their technical metadata. This is powered by an AI auto-tagging system.
Sources: packages/webapp/src/app/blog/introducing-use-cases/page.tsx
AI-Powered Auto-Tagging
When a package is published, an AI enrichment process analyzes its name, description, README, and content to automatically assign relevant use case tags (e.g., "API Development", "Debugging & Troubleshooting").
The process involves:
- Text Extraction: Gathers all textual content from the package.
- Keyword and Fuzzy Matching: Matches content against a predefined list of keywords for each use case.
- Scoring: Ranks potential use cases based on confidence.
- Tagging: Applies the top 1-3 most relevant use cases to the package.
This allows users to browse the /use-cases page or filter search results by a specific problem domain.
This diagram shows the automated pipeline for tagging packages with relevant use cases upon publication.
Sources: packages/webapp/src/app/blog/introducing-use-cases/page.tsx
Format Compatibility and agents.md
A key aspect of PRPM's discovery is its cross-format compatibility. The platform supports multiple AI IDE formats, but agents.md is highlighted as a tool-agnostic open standard.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx, packages/webapp/src/app/blog/format-specifications-guide/page.tsx
The agents.md Standard
The agents.md format is designed for radical simplicity: it is a single, plain markdown file with no required frontmatter, special syntax, or tool-specific features. This makes it a universal format that can be supported by any AI coding tool, including OpenAI Codex, GitHub Copilot, and Google Gemini. PRPM's parser for agents.md is designed to be flexible, handling optional frontmatter and extracting descriptions from the first paragraph if not explicitly provided.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx, packages/converters/src/tests/from-agents-md.test.ts:18-24
Format Comparison
PRPM's search and installation system is aware of the different formats, allowing a user to find a package in one format and install it as another. The agents.md format serves as a neutral, portable standard.
| Format | File Location | Structure | Cross-Tool Support |
|---|---|---|---|
| agents.md | AGENTS.md | Flexible markdown | ✅ Yes |
| Cursor | .cursor/rules/ | Plain text rules | ❌ Cursor only |
| GitHub Copilot | .github/copilot-instructions.md | Markdown with frontmatter | ⚠️ Partial (also reads agents.md) |
| Claude | .claude/skills/*.md | Directory of skills | ❌ Claude only |
| Continue | .continue/rules/*.md | Directory of rules | ❌ Continue only |
| Windsurf | .windsurf/rules/ | Directory of rules | ❌ Windsurf only |
This table highlights that agents.md is the only format explicitly designed for cross-tool compatibility, reinforcing its importance in the PRPM ecosystem.
Sources: packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
Conclusion
The Search and Discovery API is fundamental to the PRPM user experience. By combining traditional keyword search, advanced AI semantic search, and a problem-oriented "Use Case" discovery model, it effectively tackles the challenge of finding relevant packages in a large registry. Furthermore, its deep integration with PRPM's format conversion engine and its support for open standards like agents.md empower developers to work across a diverse and fragmented ecosystem of AI coding tools, fulfilling the platform's core promise of universal compatibility.
Sources: packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx, packages/webapp/src/app/blog/introducing-use-cases/page.tsx