# Opus Genesis - API Documentation for LLMs

> This file provides information about the Opus Genesis API for Large Language Models.
> Base URL: https://opusgenesis.com

## Overview

Opus Genesis is a platform featuring curated content, products, and community features.
Most API endpoints are public and return JSON data following the PayloadCMS REST API format.

## Authentication

Most read endpoints are public and do not require authentication.
Write operations (POST, PATCH, DELETE) require authentication via Clerk session cookies.

## Response Format

All endpoints return JSON in PayloadCMS format:
```json
{
  "docs": [...],        // Array of results
  "totalDocs": 100,     // Total matching documents
  "limit": 10,          // Results per page
  "totalPages": 10,     // Total pages
  "page": 1,            // Current page
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}
```

## Public API Endpoints

### Products

Get all products:
```
GET /api/products
```

Get a specific product by ID:
```
GET /api/products/{id}
```

Query parameters:
- `limit` - Results per page (default: 10, max: 100)
- `page` - Page number (default: 1)
- `depth` - Relationship depth (0-3, default: 1)
- `where[fieldName][operator]` - Filter results
- `sort` - Sort field (prefix with `-` for descending)

Example queries:
```
GET /api/products?limit=20
GET /api/products?where[featured][equals]=true
GET /api/products?where[name][contains]=T-Shirt
GET /api/products?where[slug][equals]=classic-cotton-tshirt
GET /api/products?sort=-createdAt
```

Product fields:
- `id` - Unique identifier
- `name` - Product name
- `slug` - URL-friendly identifier
- `description` - Product description
- `price` - Base price
- `compareAtPrice` - Original/compare-at price
- `sku` - Stock keeping unit
- `inventory` - Stock quantity
- `featured` - Featured product flag
- `images` - Product images (relationship)
- `variants` - Product variants (size, color, etc.)
- `createdAt`, `updatedAt` - Timestamps

### User Profiles

Get all user profiles:
```
GET /api/user-profiles
```

Get a specific profile by ID:
```
GET /api/user-profiles/{id}
```

Query parameters: (same as products)

Example queries:
```
GET /api/user-profiles?limit=20
GET /api/user-profiles?where[profession][contains]=Designer
GET /api/user-profiles?where[displayName][contains]=Smith
```

Profile fields:
- `id` - Unique identifier
- `user` - User relationship
- `displayName` - Public display name
- `profession` - Job title/role
- `affiliation` - Company/organization
- `bio` - Biography text
- `avatar` - Avatar image (relationship)
- `twitterUrl`, `linkedinUrl` - Social links
- `createdAt`, `updatedAt` - Timestamps

### Posts (Blog/Editorial Content)

Get all posts:
```
GET /api/posts
```

Get a specific post by ID:
```
GET /api/posts/{id}
```

Example queries:
```
GET /api/posts?where[_status][equals]=published
GET /api/posts?where[category][equals]=Fashion Trends
GET /api/posts?sort=-createdAt
GET /api/posts?where[featured][equals]=true
```

Post fields:
- `id` - Unique identifier
- `title` - Post title
- `slug` - URL-friendly identifier
- `category` - Post category (Fashion Trends, Runway, Style Guide, etc.)
- `publishedDate` - Publication date
- `excerpt` - Short summary
- `content` - Rich text content (Lexical JSON)
- `coverUrl` - Cover image URL
- `brand` - Associated brand (optional)
- `fashionCollection` - Fashion collection (e.g., "Fall/Winter 2025")
- `magazine` - Magazine source (optional)
- `designer` - Designer name (optional)
- `tags` - Array of tags
- `variant` - Layout variant ("vertical" or "horizontal")
- `featured` - Featured flag
- `createdAt`, `updatedAt` - Timestamps
- `_status` - "published" or "draft"

### Media (Images/Files)

Get all media:
```
GET /api/media
```

Get a specific media item by ID:
```
GET /api/media/{id}
```

Media fields:
- `id` - Unique identifier
- `url` - Direct URL to file
- `filename` - Original filename
- `mimeType` - File MIME type
- `filesize` - Size in bytes
- `width`, `height` - Dimensions (for images)
- `alt` - Alt text description
- `createdAt`, `updatedAt` - Timestamps

### Search

Unified search across products, posts, and user profiles:
```
GET /api/search
```

Query parameters:
- `where[title][contains]` - Search query
- `limit` - Results per page
- `page` - Page number

Example:
```
GET /api/search?where[title][contains]=fashion&limit=20
```

Search result fields:
- `title` - Result title
- `description` - Result description
- `doc` - Reference to original document
  - `relationTo` - Collection name ("products", "posts", "user-profiles")
  - `value` - Document ID

## Query Operators

Available operators for `where` clauses:
- `equals` - Exact match
- `not_equals` - Not equal
- `contains` - Contains substring (case-insensitive)
- `in` - Value in array
- `not_in` - Value not in array
- `all` - All values in array
- `greater_than` - Numeric comparison
- `greater_than_equal` - Numeric comparison
- `less_than` - Numeric comparison
- `less_than_equal` - Numeric comparison
- `exists` - Field exists (true/false)

Example:
```
GET /api/products?where[inventory][greater_than]=0
GET /api/posts?where[createdAt][greater_than]=2024-01-01
```

## Complex Queries

Combine multiple conditions with `and` / `or`:
```
GET /api/products?where[and][0][featured][equals]=true&where[and][1][inventory][greater_than]=0
GET /api/posts?where[or][0][category][equals]=Fashion Trends&where[or][1][category][equals]=Runway
```

## Relationship Depth

Use `depth` parameter to populate relationships:
- `depth=0` - IDs only
- `depth=1` - First level relationships populated (default)
- `depth=2` - Nested relationships populated
- `depth=3` - Maximum depth

Example:
```
GET /api/products/123?depth=2
```
Returns product with:
- Product images populated (depth 1)
- Image metadata included (depth 2)

## Rate Limiting

No official rate limits currently enforced for read operations.
Please be respectful and cache responses when possible.

## Best Practices

1. **Use pagination**: Always set a reasonable `limit` (default is 10)
2. **Filter published content**: Add `where[_status][equals]=published` for public data
3. **Use depth wisely**: Higher depth = larger responses
4. **Cache responses**: Data doesn't change instantly
5. **Handle errors**: Check HTTP status codes (200 = success, 404 = not found)

## Example Use Cases

### Get all featured products
```
GET /api/products?where[featured][equals]=true
```

### Find products in stock
```
GET /api/products?where[inventory][greater_than]=0&sort=-createdAt
```

### Get recent published posts
```
GET /api/posts?where[_status][equals]=published&sort=-createdAt&limit=10
```

### Search for posts by category
```
GET /api/posts?where[category][equals]=Fashion Trends&limit=20
```

### Get featured editorial content
```
GET /api/posts?where[and][0][featured][equals]=true&where[and][1][_status][equals]=published
```

## Technical Details

- **Stack**: Next.js 15, PayloadCMS 3, PostgreSQL
- **Hosting**: Vercel
- **Response Format**: JSON (PayloadCMS REST API)
- **CORS**: Enabled for public endpoints
- **SSL**: All requests must use HTTPS

## Contact

For API support or questions:
- Website: https://opusgenesis.com
- Admin Panel: https://opusgenesis.com/admin

## Additional Resources

- PayloadCMS REST API Docs: https://payloadcms.com/docs/rest-api/overview
- Query Documentation: https://payloadcms.com/docs/queries/overview

---

Last Updated: 2025-10-15