Registry API Overview
Relevant source files
The following files were used as context for generating this wiki page:The PRPM Registry is the central backend service for the Prompt Package Manager. It is a Node.js application built with Fastify that handles user authentication, package management, search, and download statistics. It serves as the authoritative source for all packages, collections, and user data within the PRPM ecosystem.
The registry is designed to be a high-performance, scalable API that interacts with a PostgreSQL database for persistent storage, Redis for caching, and an S3-compatible object storage for package content. It exposes a RESTful API for clients like the prpm CLI and the web application.
Sources: packages/registry/README.md
Architecture
The registry follows a standard modern web service architecture, utilizing a combination of a web framework, database, cache, and object storage to deliver its functionality.
This diagram shows the high-level interaction between clients and the registry's backend components.
Sources: packages/registry/README.md
Tech Stack
The backend is built on a foundation of robust and widely-used technologies.
| Component | Technology | Purpose |
|---|---|---|
| Runtime | Node.js 20+ | JavaScript runtime environment. |
| Framework | Fastify | High-performance web framework for building the API. |
| Database | PostgreSQL 15+ | Primary data store for users, packages, etc. |
| Cache | Redis 7+ | Caching layer for API responses to improve performance. |
| Storage | S3-compatible | Object storage for package tarballs and other assets. |
| Search | PostgreSQL | Full-text search capabilities using pg_trgm. |
Sources: packages/registry/README.md
Key Features
The registry provides a comprehensive set of features for managing AI prompts as packages.
- GitHub OAuth Authentication: Secure user login and authentication via GitHub.
- Package Management: Endpoints for publishing, searching, and downloading packages and collections.
- Full-Text Search: PostgreSQL-powered search for packages.
- Redis Caching: Intelligent caching for fast response times on frequently accessed data.
- Download Statistics: Tracks package popularity and trends.
- Tags & Categories: Organizes packages for better discovery.
- Ratings & Reviews: A community feedback system.
- API Tokens: Secure authentication for the CLI.
- Swagger Documentation: Interactive API documentation available at the
/docsendpoint.
Sources: packages/registry/README.md
Authentication
Authentication is handled via a GitHub OAuth2 flow. The CLI or webapp initiates the flow, and upon successful authentication with GitHub, the registry issues a JWT for subsequent authenticated requests. The CLI can also use long-lived API tokens.
This sequence diagram illustrates the GitHub OAuth login process.
API Endpoints
The registry exposes a versioned API under the /api/v1/ prefix.
| Method | Endpoint | Description |
|---|---|---|
| Authentication | ||
GET | /api/v1/auth/github | Initiates the GitHub OAuth flow. |
GET | /api/v1/auth/github/callback | Handles the OAuth callback from GitHub. |
GET | /api/v1/auth/me | Retrieves the profile of the currently authenticated user. |
POST | /api/v1/auth/token | Generates a new API token for CLI authentication. |
| Packages | ||
GET | /api/v1/packages | Lists packages with pagination. |
GET | /api/v1/packages/:id | Retrieves details for a specific package. |
GET | /api/v1/packages/:id/:version | Retrieves a specific version of a package. |
POST | /api/v1/packages | Publishes a new package (auth required). |
DELETE | /api/v1/packages/:id/:version | Unpublishes a package version (auth required). |
GET | /api/v1/packages/:id/stats | Gets download statistics for a package. |
| Search | ||
GET | /api/v1/search?q=<query> | Performs a full-text search for packages. |
GET | /api/v1/search/trending | Lists trending packages. |
GET | /api/v1/search/featured | Lists featured packages. |
GET | /api/v1/search/tags | Retrieves a list of all available tags. |
GET | /api/v1/search/categories | Retrieves a list of all categories. |
GET | /api/v1/search/seo/packages | SEO-optimized endpoint returning only package names. |
GET | /api/v1/search/seo/collections | SEO-optimized endpoint returning only collection slugs. |
| Users | ||
GET | /api/v1/users/:username | Retrieves a user's public profile. |
GET | /api/v1/users/:username/packages | Lists packages published by a specific user. |
| Schemas | ||
GET | /api/v1/schemas/{format}.json | Retrieves the base JSON schema for a given format. |
GET | /api/v1/schemas/{format}/{subtype}.json | Retrieves a subtype-specific JSON schema. |
| Health | ||
GET | /health | Health check endpoint for monitoring. |
Sources: packages/registry/README.md, packages/converters/schemas/README.md, packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx, packages/webapp/BUILDING.md
Schema Service
A key feature of the registry is its ability to serve JSON schemas for all supported AI prompt formats. These schemas are used by the prpm CLI for validation during publishing and by IDEs for features like autocomplete and inline documentation.
The schemas are accessible via the /api/v1/schemas/ endpoint. This service allows any tool to programmatically fetch the validation rules for formats like cursor, claude, windsurf, and more.
Example Schema Endpoints
https://registry.prpm.dev/api/v1/schemas/cursor.jsonhttps://registry.prpm.dev/api/v1/schemas/claude/agent.jsonhttps://registry.prpm.dev/api/v1/schemas/claude/skill.json
Sources: packages/converters/schemas/README.md, packages/webapp/src/app/blog/json-schemas-for-ai-prompts/page.tsx
Database Schema
The PostgreSQL database stores all persistent data. The schema is managed via migration files.
This ER diagram shows the main tables and their relationships.
Sources: packages/registry/README.md
Caching Strategy
Redis is used extensively to reduce database load and improve API response times. Caches are automatically invalidated when underlying data changes (e.g., a new package version is published).
| Data | Cache Duration | Invalidation Trigger |
|---|---|---|
| Package listings | 5 minutes | Package publish/unpublish |
| Package details | 5 minutes | Package metadata update |
| Package versions | 1 hour (immutable) | N/A |
| Search results | 5 minutes | New package publish |
| Trending/Featured | 1 hour | N/A (time-based) |
| Tags/Categories | 1 hour | N/A (time-based) |
Sources: packages/registry/README.md
Monitoring
The registry provides a GET /health endpoint for monitoring and health checks. It returns a simple JSON object indicating the service status and application version.
{
"status": "ok",
"timestamp": "2025-10-17T20:00:00.000Z",
"version": "1.0.0"
}
Sources: packages/registry/README.md
Conclusion
The Registry API is the backbone of the PRPM ecosystem. It provides a centralized, secure, and performant service for managing the entire lifecycle of AI prompts, agents, and rules. Its feature set, including robust authentication, package management, search, and caching, enables a seamless experience for both developers consuming packages and authors publishing them. The API's design ensures that clients like the CLI and webapp have a reliable and consistent interface for interacting with the PRPM platform.