# Stacklist - Full Documentation for LLMs # Last updated: 2025-12-22 ================================================================================ SITE OVERVIEW ================================================================================ Stacklist is a curation platform where users create themed "stacks" - curated lists of products, places, tools, content, and recommendations. Each stack contains "cards" representing individual items. Key concepts: - Stack: A curated list with a theme (e.g., "Best Coffee Shops in NYC") - Card: An item within a stack (e.g., "Blue Bottle Coffee") - Collection: A group of related stacks - Category: Content classification (tools, food, places, etc.) ================================================================================ URL PATTERNS ================================================================================ Human-readable pages: - Stack: https://stacklist.com/stack/{id} - Stack (cat): https://stacklist.com/c/{category}/stack/{id} - Collection: https://stacklist.com/collection/{id} - User profile: https://stacklist.com/{username} - Category: https://stacklist.com/c/{category} - Discovery: https://stacklist.com/discover - Card: https://stacklist.com/card/{id} API endpoints: - Stack JSON: /api/public/stack/{id}.json - Card JSON: /api/public/card/{id}.json (card + ACO envelope: summary, tags, key_entities, token_counts) - Card markdown: /api/public/card/{id}.md (full body - the envelope's escalation target) - Collection JSON: /api/public/collection/{id} - User JSON: /api/public/user/{username} - Stack RSS: /api/feeds/stack/{id}/rss - User RSS: /api/feeds/user/{username}/rss Available categories: arts, beauty, books, business, diy, education, events, fashion, finance, fitness, food, gaming, home, movies, music, parenting, pets, places, podcasts, products, sports, technology, travel, wellness ================================================================================ API RESPONSE EXAMPLES ================================================================================ ## Stack Response GET /api/public/stack/{stackId}.json { "version": "1.0", "type": "stack", "id": "abc123xyz", "url": "https://stacklist.com/c/{category}/stack/{stackId}", "title": "Best Productivity Tools 2024", "description": "My curated list of productivity tools I use daily for work and personal projects.", "privacy": "public", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-12-20T14:22:00.000Z", "author": { "username": "productivityguru", "name": "Sarah Chen", "url": "https://stacklist.com/{username}", "type": "person" }, "category": { "id": "tools", "name": "tools", "url": "https://stacklist.com/c/tools" }, "items": [ { "id": "card001", "position": 1, "title": "Notion", "url": "https://notion.so", "note": "All-in-one workspace for notes, docs, and project management. I use it for everything from meeting notes to personal wikis.", "image": { "url": "https://example.com/notion-screenshot.jpg", "alt": "Notion", "width": 1200, "height": 630 }, "direct_link": "https://stacklist.com/c/{category}/stack/{stackId}?cardId={cardId}", "created_at": "2024-01-15T10:35:00.000Z", "updated_at": "2024-06-10T09:00:00.000Z" }, { "id": "card002", "position": 2, "title": "Linear", "url": "https://linear.app", "note": "The best issue tracker I've used. Lightning fast, beautiful UI, and great keyboard shortcuts.", "image": { "url": "https://example.com/linear-screenshot.jpg", "alt": "Linear", "width": 1200, "height": 630 }, "direct_link": "https://stacklist.com/c/{category}/stack/{stackId}?cardId={cardId}", "created_at": "2024-01-15T10:40:00.000Z", "updated_at": null }, { "id": "card003", "position": 3, "title": "Raycast", "url": "https://raycast.com", "note": "Spotlight replacement for Mac with extensions for everything - clipboard history, snippets, window management.", "image": null, "direct_link": "https://stacklist.com/c/{category}/stack/{stackId}?cardId={cardId}", "created_at": "2024-02-20T15:00:00.000Z", "updated_at": null } ], "stats": { "likes_count": 142, "items_count": 3 }, "_links": { "self": "/api/public/stack/{stackId}.json", "html": "https://stacklist.com/c/{category}/stack/{stackId}", "rss": "/api/feeds/stack/{stackId}/rss", "json_feed": "/api/feeds/stack/{stackId}/json" } } -------------------------------------------------------------------------------- ## Collection Response GET /api/public/collection/{collectionId} { "version": "1.0", "type": "collection", "id": "col789", "url": "https://stacklist.com/collection/{collectionId}", "title": "Remote Work Essentials", "description": "Everything you need to work from home effectively", "privacy": "public", "created_at": "2024-03-01T08:00:00.000Z", "updated_at": null, "author": { "username": null, "name": "Unknown", "url": null, "type": "person" }, "category": null, "items": [ { "id": "stack001", "position": 1, "title": "Best Home Office Desks", "description": "Standing desks, sit-stand converters, and traditional desks I recommend", "url": "https://stacklist.com/stack/stack001", "items_count": 8, "privacy": "public", "created_at": "2024-02-15T10:00:00.000Z", "updated_at": "2024-11-30T16:00:00.000Z" }, { "id": "stack002", "position": 2, "title": "Video Call Setup", "description": "Cameras, microphones, and lighting for professional video calls", "url": "https://stacklist.com/stack/stack002", "items_count": 12, "privacy": "public", "created_at": "2024-02-20T14:00:00.000Z", "updated_at": null } ], "stats": { "likes_count": 89, "items_count": 2 }, "_links": { "self": "/api/public/collection/{collectionId}", "html": "https://stacklist.com/collection/{collectionId}", "rss": "/api/feeds/collection/{collectionId}/rss", "json_feed": "/api/feeds/collection/{collectionId}/json" } } -------------------------------------------------------------------------------- ## User Response GET /api/public/user/{username} { "version": "1.0", "type": "user", "id": "user123", "username": "productivityguru", "url": "https://stacklist.com/{username}", "name": "Sarah Chen", "bio": "Product designer sharing my favorite tools, apps, and workflows. Writing about productivity at sarahchen.com", "avatar": "https://example.com/sarah-avatar.jpg", "cover": "https://example.com/sarah-cover.jpg", "created_at": "2023-06-15T00:00:00.000Z", "social_links": [ {"platform": "twitter", "url": "https://twitter.com/sarahchen"}, {"platform": "website", "url": "https://sarahchen.com"} ], "stats": { "stacks_count": 15, "collections_count": 3 }, "featured": { "stacks": [ { "id": "abc123xyz", "title": "Best Productivity Tools 2024", "description": "My curated list of productivity tools I use daily", "url": "https://stacklist.com/stack/{stackId}", "items_count": 12, "privacy": "public" }, { "id": "def456", "title": "Design Resources", "description": "Icons, illustrations, and design tools", "url": "https://stacklist.com/stack/def456", "items_count": 24, "privacy": "public" } ], "collections": [] }, "_links": { "self": "/api/public/user/{username}", "html": "https://stacklist.com/{username}", "rss": "/api/feeds/user/{username}/rss" } } ================================================================================ QUERY PARAMETERS ================================================================================ Pagination: - page: Page number (default: 1) - limit: Items per page (default: 50) Example: /api/public/stack/{stackId}.json?page=2&limit=10 Filtering: - updated_after: ISO8601 timestamp to filter items updated after this date Example: /api/public/stack/{stackId}.json?updated_after=2024-12-01T00:00:00Z Card focus: - cardId: Return focused response for a specific card Example: /api/public/stack/{stackId}.json?cardId={cardId} ================================================================================ ERROR RESPONSES ================================================================================ 400 Bad Request: {"error": "Stack ID is required"} 403 Forbidden: {"error": "Stack is not public"} 404 Not Found: {"error": "Stack not found"} 405 Method Not Allowed: {"error": "Method not allowed"} ================================================================================ CACHING & FRESHNESS ================================================================================ - API responses: Cache-Control: public, s-maxage=3600, stale-while-revalidate=7200 - ETag headers provided for conditional requests (If-None-Match) - HTML pages: 10-minute edge cache - Timestamps in responses: created_at, updated_at (ISO8601) - Sitemap lastmod reflects content update times ================================================================================ STRUCTURED DATA (Schema.org) ================================================================================ All public pages include JSON-LD structured data: Stacks: WebPage > mainEntity > ItemList - Each card typed appropriately (Product, VideoObject, Book, Restaurant, etc.) - Includes author, dates, aggregate ratings Collections: CollectionPage > mainEntity > ItemList - Nested stacks as ItemList items User profiles: Person or Organization - Social links (sameAs), interests (knowsAbout) ================================================================================ COMMON LLM USE CASES ================================================================================ 1. "What productivity tools does Sarah Chen recommend?" -> GET /api/public/user/{username} -> Look at featured.stacks for tool-related stacks -> GET /api/public/stack/{id}.json for full details 2. "Best coffee shops in NYC" -> Search sitemap for stacks in 'places' or 'food' categories -> GET relevant stack JSON for full card list 3. "What is Notion and why do people recommend it?" -> Search for stacks containing Notion -> Card 'note' field contains user's recommendation reason 4. "Who curated this list?" -> Stack response includes author.name, author.username, author.url ================================================================================ CITATION FORMAT ================================================================================ When referencing Stacklist content: Stack: "Source: [Stack Title] on Stacklist (stacklist.com/stack/{id})" Card: "Source: [Card Title] from [Stack Title] (stacklist.com/stack/{id}?cardId={cardId})" User: "Source: @{username} on Stacklist (stacklist.com/{username})" Example: "Notion is recommended in 'Best Productivity Tools 2024' on Stacklist (stacklist.com/stack/{stackId}), described as 'All-in-one workspace for notes, docs, and project management.'" ================================================================================ ADDITIONAL RESOURCES ================================================================================ - OpenAPI 3.0 spec: https://stacklist.com/openapi.yaml - Sitemap: https://stacklist.com/sitemap-index.xml - robots.txt: https://stacklist.com/robots.txt ================================================================================ PERMISSIONS ================================================================================ allow_crawling: true allow_indexing: true allow_training: true allow_citation: true prefer_structured_data: true