# Prompts.chat - AI Prompt Library Platform

## Introduction

Prompts.chat (formerly Awesome ChatGPT Prompts) is a self-hostable, community-driven platform for creating, discovering, and sharing AI prompts. Built with Next.js 16, React 19, Prisma, and PostgreSQL, it provides a comprehensive prompt management system with version control, AI-powered semantic search, webhooks, and multi-language support. The platform serves as both a public prompt library at prompts.chat and a white-labelable solution for organizations to deploy their own private prompt repositories with customizable branding, themes, and authentication.

This application features a RESTful API for prompt CRUD operations, category subscriptions, user management, and leaderboards. It supports multiple prompt types (text, image, video, audio, structured JSON/YAML), change request workflows similar to pull requests, voting systems, private/public prompts, and webhook integrations for real-time notifications. All prompts are released under CC0 (public domain), making them freely usable for any purpose without attribution requirements.

## API Endpoints and Functions

### Create a New Prompt

Create a new prompt with support for multiple types, tags, categories, and media attachments.

```typescript
// POST /api/prompts
const response = await fetch('https://prompts.chat/api/prompts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cookie': 'session=your-session-token'
  },
  body: JSON.stringify({
    title: "Linux Terminal Expert",
    description: "Act as a Linux terminal and respond to commands",
    content: "I want you to act as a linux terminal. I will type commands and you will reply with what the terminal should show. I want you to only reply with the terminal output inside one unique code block, and nothing else.",
    type: "TEXT",
    structuredFormat: null,
    categoryId: "clx1234567890",
    tagIds: ["tag-id-1", "tag-id-2"],
    contributorIds: ["user-id-1"],
    isPrivate: false,
    mediaUrl: "",
    requiresMediaUpload: false
  })
});

const prompt = await response.json();
// Returns: { id, title, slug, content, author, category, tags, createdAt, updatedAt }
// Automatically creates initial version, triggers webhooks, generates AI embeddings
```

### List and Search Prompts

Retrieve paginated prompts with filtering by type, category, tag, and keyword search.

```typescript
// GET /api/prompts?page=1&perPage=12&type=TEXT&category=clx123&tag=productivity&sort=upvotes&q=linux
const url = new URL('https://prompts.chat/api/prompts');
url.searchParams.set('page', '1');
url.searchParams.set('perPage', '12');
url.searchParams.set('type', 'TEXT');
url.searchParams.set('category', 'clx1234567890');
url.searchParams.set('tag', 'productivity');
url.searchParams.set('sort', 'upvotes'); // 'oldest', 'upvotes', or default 'newest'
url.searchParams.set('q', 'linux terminal');

const response = await fetch(url);
const data = await response.json();
/*
{
  prompts: [
    {
      id: "clx...",
      title: "Linux Terminal Expert",
      description: "Act as a Linux terminal...",
      content: "I want you to act as...",
      type: "TEXT",
      author: { id, name, username, avatar },
      category: { id, name, slug },
      tags: [{ tag: { id, name, slug, color } }],
      voteCount: 42,
      contributorCount: 3,
      createdAt: "2025-01-15T..."
    }
  ],
  total: 150,
  page: 1,
  perPage: 12,
  totalPages: 13
}
*/
```

### Get Single Prompt Details

Fetch a specific prompt by ID with full details including version history.

```typescript
// GET /api/prompts/:id
const response = await fetch('https://prompts.chat/api/prompts/clx1234567890', {
  headers: {
    'Cookie': 'session=your-session-token' // Required for private prompts
  }
});

const prompt = await response.json();
/*
{
  id: "clx1234567890",
  title: "Linux Terminal Expert",
  slug: "linux-terminal-expert",
  description: "Act as a Linux terminal...",
  content: "I want you to act as a linux terminal...",
  type: "TEXT",
  structuredFormat: null,
  isPrivate: false,
  mediaUrl: null,
  viewCount: 1523,
  author: {
    id: "user-123",
    name: "John Doe",
    username: "johndoe",
    avatar: "https://..."
  },
  category: { id, name, slug, description, icon },
  tags: [
    { tag: { id, name, slug, color } }
  ],
  versions: [
    { id, version: 2, content: "...", changeNote: "Fixed typo", createdAt },
    { id, version: 1, content: "...", changeNote: "Initial version", createdAt }
  ],
  createdAt: "2025-01-15T10:30:00Z",
  updatedAt: "2025-01-16T14:20:00Z"
}
*/
```

### Update an Existing Prompt

Update a prompt's content, metadata, or tags (owner or admin only).

```typescript
// PATCH /api/prompts/:id
const response = await fetch('https://prompts.chat/api/prompts/clx1234567890', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Cookie': 'session=your-session-token'
  },
  body: JSON.stringify({
    title: "Advanced Linux Terminal",
    description: "Updated description",
    content: "Enhanced prompt content with new examples...",
    type: "TEXT",
    categoryId: "clx9876543210",
    tagIds: ["new-tag-1", "new-tag-2"],
    contributorIds: ["user-id-1", "user-id-2"],
    isPrivate: false
  })
});

const updated = await response.json();
// Returns updated prompt with new version created if content changed
// Automatically regenerates slug if title changed
// Regenerates AI embeddings for public prompts (non-blocking)
```

### Subscribe to Category

Subscribe to a category to get personalized feed of prompts.

```typescript
// POST /api/categories/:id/subscribe
const response = await fetch('https://prompts.chat/api/categories/clx-cat-123/subscribe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cookie': 'session=your-session-token'
  }
});

const result = await response.json();
// Returns: { subscribed: true, category: { id, name, slug } }

// DELETE /api/categories/:id/subscribe - Unsubscribe
const unsubscribe = await fetch('https://prompts.chat/api/categories/clx-cat-123/subscribe', {
  method: 'DELETE',
  headers: { 'Cookie': 'session=your-session-token' }
});
// Returns: { subscribed: false }
```

### User Registration

Register a new user account with email and password authentication.

```typescript
// POST /api/auth/register
const response = await fetch('https://prompts.chat/api/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: "Jane Smith",
    username: "janesmith",
    email: "jane@example.com",
    password: "secure-password-123"
  })
});

const user = await response.json();
/*
{
  id: "clx-user-123",
  name: "Jane Smith",
  username: "janesmith",
  email: "jane@example.com"
}
*/
// Password is hashed with bcrypt (12 rounds)
// Username must match /^[a-zA-Z0-9_]+$/
// Returns 403 if registration is disabled in config
```

### Get Leaderboard

Retrieve top contributors ranked by upvotes with time period filtering.

```typescript
// GET /api/leaderboard?period=week
const response = await fetch('https://prompts.chat/api/leaderboard?period=week');
// period options: 'all', 'month', 'week' (default: 'all')

const data = await response.json();
/*
{
  period: "week",
  leaderboard: [
    {
      id: "user-123",
      name: "John Doe",
      username: "johndoe",
      avatar: "https://...",
      totalUpvotes: 256,
      promptCount: 18
    },
    {
      id: "user-456",
      name: "Jane Smith",
      username: "janesmith",
      avatar: "https://...",
      totalUpvotes: 189,
      promptCount: 12
    }
    // ... up to 50 users, sorted by totalUpvotes descending
  ]
}
*/
// Minimum 10 users returned; fills with users with most prompts if needed
```

### Create Webhook Configuration (Admin Only)

Configure webhooks to receive notifications for prompt events.

```typescript
// POST /api/admin/webhooks
const response = await fetch('https://prompts.chat/api/admin/webhooks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cookie': 'admin-session-token'
  },
  body: JSON.stringify({
    name: "Slack Notifications",
    url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
    method: "POST",
    headers: {
      "Authorization": "Bearer token-if-needed"
    },
    payload: JSON.stringify({
      text: "New prompt: {{PROMPT_TITLE}}",
      blocks: [{
        type: "section",
        text: {
          type: "mrkdwn",
          text: "*{{PROMPT_TITLE}}*\n{{PROMPT_DESCRIPTION}}\n<{{PROMPT_URL}}|View Prompt> | <{{CHATGPT_URL}}|Run in ChatGPT>"
        }
      }]
    }),
    events: ["PROMPT_CREATED", "PROMPT_UPDATED", "PROMPT_DELETED"],
    isEnabled: true
  })
});

const webhook = await response.json();
// Returns: { id, name, url, method, headers, payload, events, isEnabled, createdAt, updatedAt }

// Available placeholders:
// {{PROMPT_ID}}, {{PROMPT_TITLE}}, {{PROMPT_DESCRIPTION}}, {{PROMPT_CONTENT}},
// {{PROMPT_TYPE}}, {{PROMPT_URL}}, {{PROMPT_MEDIA_URL}}, {{AUTHOR_USERNAME}},
// {{AUTHOR_NAME}}, {{AUTHOR_AVATAR}}, {{CATEGORY_NAME}}, {{TAGS}},
// {{TIMESTAMP}}, {{SITE_URL}}, {{CHATGPT_URL}}
```

### Generate AI Embeddings for Semantic Search

Generate vector embeddings for prompts to enable AI-powered semantic search.

```typescript
// From server-side code (not a public API endpoint)
import { generatePromptEmbedding, semanticSearch } from '@/lib/ai/embeddings';

// Generate embedding for a single prompt
await generatePromptEmbedding('clx-prompt-123');
// Combines title, description, and content
// Uses OpenAI text-embedding-3-small model (configurable via OPENAI_EMBEDDING_MODEL)
// Only generates for public prompts
// Requires OPENAI_API_KEY and features.aiSearch enabled in config

// Semantic search with AI
const results = await semanticSearch('how to debug python code', 20);
/*
[
  {
    id: "clx...",
    title: "Python Debugger Expert",
    description: "...",
    content: "...",
    similarity: 0.89,
    author: { id, name, username, avatar },
    category: { id, name, slug },
    tags: [{ tag: { id, name, slug, color } }],
    voteCount: 45,
    type: "TEXT",
    createdAt: "2025-01-10T..."
  }
  // ... sorted by similarity score (cosine similarity)
  // Only returns results with similarity >= 0.4
]
*/
```

### Trigger Webhooks Programmatically

Send webhook notifications when prompt events occur (used internally by API).

```typescript
// From server-side code
import { triggerWebhooks } from '@/lib/webhook';

// Trigger webhooks for a new prompt
await triggerWebhooks('PROMPT_CREATED', {
  id: 'clx-prompt-123',
  title: 'JavaScript Interview Questions',
  description: 'Comprehensive list of JS interview questions',
  content: 'Q: What is closure? A: ...',
  type: 'TEXT',
  mediaUrl: null,
  isPrivate: false,
  author: {
    username: 'jsexpert',
    name: 'JS Expert',
    avatar: 'https://...'
  },
  category: {
    name: 'Programming',
    slug: 'programming'
  },
  tags: [
    { tag: { name: 'javascript', slug: 'javascript' } },
    { tag: { name: 'interview', slug: 'interview' } }
  ]
});
// Fetches all enabled webhooks for PROMPT_CREATED event
// Replaces placeholders in payload templates
// Sends HTTP requests in parallel (fire-and-forget)
// Escapes JSON strings and truncates content to 2000 chars
```

### Delete Prompt (Admin Only - Soft Delete)

Soft delete a prompt by setting deletedAt timestamp (CC0 prompts cannot be deleted by users).

```typescript
// DELETE /api/prompts/:id
const response = await fetch('https://prompts.chat/api/prompts/clx1234567890', {
  method: 'DELETE',
  headers: {
    'Cookie': 'admin-session-token' // Must be ADMIN role
  }
});

const result = await response.json();
// Returns: { success: true, message: "Prompt soft deleted" }

// Non-admin users receive:
// { error: "forbidden", message: "Prompts are released under CC0 and cannot be deleted. Contact an admin if there is an issue." }
// Soft-deleted prompts have deletedAt timestamp set but are not physically removed
// Soft-deleted prompts are excluded from public queries
```

## Summary and Integration

Prompts.chat provides a production-ready platform for teams and organizations to manage AI prompts with enterprise features including authentication (GitHub, Google, Azure AD, email/password), role-based access control (USER/ADMIN), version control with change requests, voting systems, category subscriptions, and real-time webhook notifications. The platform scales to support large prompt libraries with AI-powered semantic search using OpenAI embeddings, efficient pagination, and optimized PostgreSQL queries with proper indexing on frequently queried fields.

Integration patterns include using the REST API for programmatic access to prompts, webhooks for real-time synchronization with external systems (Slack, Discord, CMS platforms), semantic search for intelligent prompt discovery, and self-hosting with full white-label customization through the `prompts.config.ts` configuration file. The platform supports multi-tenant deployments with private prompts, customizable branding (logo, colors, themes), internationalization (14 languages supported), and flexible authentication providers. Database migrations are managed through Prisma ORM with seeding support, and the application follows Next.js 16 App Router conventions with React Server Components for optimal performance.