{ "openapi": "3.0.3", "info": { "title": "PlanMyPC API", "version": "0.1.0", "description": "OpenAPI spec generated from Next.js App Router route handlers in src/app/api. The generator statically analyzes exported handlers, parameters, response branches, and inline comments to keep the published API surface tied to the code." }, "servers": [ { "url": "http://localhost:3000", "description": "Local development" }, { "url": "https://planmypc.com", "description": "Production" } ], "tags": [ { "name": "admin" }, { "name": "alerts" }, { "name": "amazon" }, { "name": "analytics" }, { "name": "auth" }, { "name": "benchmarks" }, { "name": "build" }, { "name": "builds" }, { "name": "catalog-proposals" }, { "name": "ci" }, { "name": "comments" }, { "name": "compatibility" }, { "name": "consent" }, { "name": "contact" }, { "name": "cron" }, { "name": "csp-report" }, { "name": "email" }, { "name": "errors" }, { "name": "export" }, { "name": "feeds" }, { "name": "forums" }, { "name": "game-fps" }, { "name": "guides" }, { "name": "health" }, { "name": "internal" }, { "name": "news" }, { "name": "newsletter" }, { "name": "notifications" }, { "name": "parametric" }, { "name": "price-alerts" }, { "name": "prices" }, { "name": "products" }, { "name": "reviews" }, { "name": "saved-items" }, { "name": "search" }, { "name": "seed-benchmarks" }, { "name": "trends" }, { "name": "users" }, { "name": "v1" }, { "name": "wishlist" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "PlanMyPC API key", "description": "PlanMyPC API key issued from /api/v1/keys. Send it as `Authorization: Bearer pmpc_`. Keys are scoped (products:read, builds:read, prices:read) and rate limited per key." }, "serverTokenAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque token", "description": "Opaque server-to-server bearer token (e.g. ADMIN_API_KEY / CRON_SECRET). Not a `pmpc_` API key." }, "supabaseSession": { "type": "apiKey", "in": "cookie", "name": "sb-access-token", "description": "Supabase session cookie set by the browser after sign-in. Used by first-party endpoints rather than the public API-key surface." } } }, "paths": { "/api/admin/catalog-proposals": { "get": { "operationId": "getAdminCatalogProposals", "summary": "List catalog proposals", "tags": [ "admin" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/admin/catalog-proposals`." } }, "/api/admin/catalog-proposals/{id}": { "get": { "operationId": "getAdminCatalogProposalsId", "summary": "Get catalog proposals by id", "tags": [ "admin" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/admin/catalog-proposals/{id}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/admin/catalog-proposals/{id}/actions": { "post": { "operationId": "postAdminCatalogProposalsIdActions", "summary": "Create actions", "tags": [ "admin" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/admin/catalog-proposals/{id}/actions`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/admin/catalog-proposals/metrics": { "get": { "operationId": "getAdminCatalogProposalsMetrics", "summary": "List metrics", "tags": [ "admin" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/admin/catalog-proposals/metrics`. Query params: `windowDays`.", "parameters": [ { "name": "windowDays", "in": "query", "required": false, "description": "windowDays parameter.", "schema": { "type": "string" } } ] } }, "/api/admin/moderation/journal-entries/{entryId}": { "patch": { "operationId": "patchAdminModerationJournalEntriesEntryId", "summary": "Patch journal entries", "tags": [ "admin" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "additionalProperties": true }, "reportsResolved": { "type": "number" }, "reportStatus": { "type": "string", "enum": [ "ACTIONED", "DISMISSED" ] } }, "required": [ "entry", "reportStatus", "reportsResolved" ] }, "example": { "entry": {}, "reportsResolved": 1, "reportStatus": "ACTIONED" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/admin/moderation/journal-entries/{entryId}`.", "parameters": [ { "name": "entryId", "in": "path", "required": true, "description": "entryId parameter.", "schema": { "type": "string" } } ] } }, "/api/alerts": { "get": { "operationId": "getAlerts", "summary": "List alerts for the current user", "tags": [ "alerts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/alerts`." }, "post": { "operationId": "postAlerts", "summary": "Create a new alert", "tags": [ "alerts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/alerts`." } }, "/api/alerts/{id}": { "put": { "operationId": "putAlertsId", "summary": "Update an alert", "tags": [ "alerts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/alerts/{id}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] }, "delete": { "operationId": "deleteAlertsId", "summary": "Delete an alert", "tags": [ "alerts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] }, "example": { "success": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/alerts/{id}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/alerts/check": { "post": { "operationId": "postAlertsCheck", "summary": "Run price alert evaluation", "tags": [ "alerts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "emailsSent": { "type": "number" }, "message": { "type": "string" }, "triggered": { "type": "number" } }, "required": [ "emailsSent", "message", "triggered" ] }, { "type": "object", "properties": { "active": { "type": "number" }, "emailsSent": { "type": "number" }, "message": { "type": "string" }, "parametricDrain": { "oneOf": [ { "type": "object", "properties": { "alertsRaised": { "type": "number" }, "batches": { "type": "number" }, "batchesHeld": { "type": "number" }, "candidateRowsRead": { "type": "number" }, "dryRun": { "type": "boolean" }, "elapsedMs": { "type": "number" }, "linesEvaluated": { "type": "number" }, "ran": { "type": "boolean" }, "source": { "type": "string" }, "winnersChanged": { "type": "number" } }, "required": [ "alertsRaised", "batches", "batchesHeld", "candidateRowsRead", "dryRun", "elapsedMs", "linesEvaluated", "ran", "source", "winnersChanged" ] }, { "type": "object", "additionalProperties": true } ] }, "parametricWakes": { "type": "number" }, "stockAlertsTriggered": { "type": "number" }, "stockEmailsSent": { "type": "number" }, "triggered": { "type": "number" } }, "required": [ "active", "emailsSent", "message", "parametricDrain", "parametricWakes", "stockAlertsTriggered", "stockEmailsSent", "triggered" ] } ] }, "example": { "emailsSent": 1, "message": "string", "triggered": 1 } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Triggers and deactivates alerts where current price <= targetPrice. Processes in batches of 500 to avoid OOM with large alert volumes. Auth: Authorization: Bearer $CRON_SECRET Also exported as GET below so the Vercel cron entry in vercel.json (every 15 minutes) actually reaches the handler. Vercel cron sends GET; the route was 405-ing silently from 2026-05-22 (PLA-1232) until PLA-1676." }, "get": { "operationId": "getAlertsCheck", "summary": "Vercel cron invokes scheduled paths with GET. Delegate to POST so the", "tags": [ "alerts" ], "responses": { "200": { "description": "OK" } }, "description": "every-15-minute schedule in vercel.json reaches the same handler. Keeping POST exported preserves any manual / internal callers." } }, "/api/amazon": { "get": { "operationId": "getAmazon", "summary": "Search Amazon-backed product data", "tags": [ "amazon" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "asin": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "detailPageURL": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "imageUrl": { "type": "string", "nullable": true }, "isBuyBoxWinner": { "type": "boolean" }, "isNewCondition": { "type": "boolean" }, "manufacturer": { "type": "string", "nullable": true }, "mpn": { "type": "string", "nullable": true }, "price": { "type": "number", "nullable": true }, "priceFormatted": { "type": "string", "nullable": true }, "productGroup": { "type": "string", "nullable": true }, "salesRank": { "type": "number", "nullable": true }, "title": { "type": "string" } }, "required": [ "asin", "brand", "category", "detailPageURL", "features", "imageUrl", "isBuyBoxWinner", "isNewCondition", "manufacturer", "mpn", "price", "priceFormatted", "productGroup", "salesRank", "title" ] } }, "source": { "type": "string" } }, "required": [ "products", "source" ] } ] }, "example": {} } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/amazon`. Query params: `asins`, `keywords`.", "parameters": [ { "name": "asins", "in": "query", "required": false, "description": "asins parameter.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "keywords", "in": "query", "required": false, "description": "keywords parameter.", "schema": { "type": "string" } } ], "security": [ { "supabaseSession": [] } ] } }, "/api/amazon/batch-lookup": { "get": { "operationId": "getAmazonBatchLookup", "summary": "Inspect cached Amazon batch lookup status", "tags": [ "amazon" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "runtimeEntries": { "type": "number" }, "totalEntries": { "type": "number" } }, "required": [ "message", "runtimeEntries", "totalEntries" ] }, "example": { "message": "string", "runtimeEntries": 1, "totalEntries": 1 } } } } }, "description": "Body: { category?: string, // category slug filter slugs?: string[], // exact slug allow-list; when set, only these products // are processed (overrides category/limit ordering). // Use for targeted discovery of a known set (e.g. // PLA-2961: 75 current-gen GPU PDPs with no ASIN). limit?: number, // max products to process skipExisting?: boolean, // skip products that already have an asin (default: true) dryRun?: boolean, // run matcher but don't persist results (default: false) } Dry run returns a per-product breakdown (matched/rejected, inferred category, candidate title, etc.) so we can audit match quality before persisting. Returns cache stats." }, "post": { "operationId": "postAmazonBatchLookup", "summary": "Fetch Amazon products in batches", "tags": [ "amazon" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "cappedAt": { "type": "number" }, "errored": { "type": "number" }, "matched": { "type": "number" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "asin": { "type": "object", "additionalProperties": true }, "brand": { "type": "object", "additionalProperties": true }, "isNew": { "type": "object", "additionalProperties": true }, "mpn": { "type": "object", "additionalProperties": true }, "price": { "type": "object", "additionalProperties": true }, "rejectReason": { "type": "object", "additionalProperties": true }, "score": { "type": "object", "additionalProperties": true }, "title": { "type": "object", "additionalProperties": true } }, "required": [ "asin", "brand", "isNew", "mpn", "price", "rejectReason", "score", "title" ] }, "nullable": true }, "inferredCategory": { "type": "string" }, "matchedAsin": { "type": "string", "nullable": true }, "matchedBrand": { "type": "string", "nullable": true }, "matchedPrice": { "type": "number", "nullable": true }, "matchedTitle": { "type": "string", "nullable": true }, "name": { "type": "string" }, "reason": { "type": "string" }, "slug": { "type": "string" }, "slugBrand": { "type": "string", "nullable": true } }, "required": [ "inferredCategory", "matchedAsin", "matchedBrand", "matchedPrice", "matchedTitle", "name", "reason", "slug", "slugBrand" ] } }, "matchRate": { "type": "number" }, "mode": { "type": "string" }, "processed": { "type": "number" }, "rejected": { "type": "number" }, "requested": { "type": "number" } }, "required": [ "cappedAt", "errored", "matchRate", "matched", "matches", "mode", "processed", "rejected", "requested" ] }, { "type": "object", "properties": { "cacheStats": { "type": "object", "properties": { "runtimeEntries": { "type": "number" }, "totalEntries": { "type": "number" } }, "required": [ "runtimeEntries", "totalEntries" ] }, "failed": { "type": "number" }, "found": { "type": "number" }, "message": { "type": "string" }, "mode": { "type": "string" }, "total": { "type": "number" } }, "required": [ "cacheStats", "failed", "found", "message", "mode", "total" ] } ] }, "example": { "cappedAt": 1, "errored": 1, "matched": 1, "matches": [ { "candidates": [ { "asin": {}, "brand": {}, "isNew": {}, "mpn": {}, "price": {}, "rejectReason": {}, "score": {}, "title": {} } ], "inferredCategory": "string", "matchedAsin": "string", "matchedBrand": "string", "matchedPrice": 1, "matchedTitle": "string", "name": "string", "reason": "string", "slug": "string", "slugBrand": "string" } ], "matchRate": 1, "mode": "string", "processed": 1, "rejected": 1, "requested": 1 } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/amazon/batch-lookup`." } }, "/api/amazon/price": { "get": { "operationId": "getAmazonPrice", "summary": "Get the current Amazon price for a product", "tags": [ "amazon" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "found": { "type": "boolean" }, "message": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "found", "message", "slug" ] }, { "type": "object", "properties": { "asin": { "type": "string" }, "buyUrl": { "type": "string" }, "found": { "type": "boolean" }, "fresh": { "type": "boolean" }, "imageUrl": { "type": "string", "nullable": true }, "price": { "type": "number" }, "priceFormatted": { "type": "string" }, "priceFreshness": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "refresh_error", "refresh_stale", "no_data", "no_trends", "source_unavailable" ], "nullable": true }, "staleAfterHours": { "type": "number" }, "status": { "type": "string", "enum": [ "fresh", "stale", "unavailable" ] }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "staleAfterHours", "status", "updatedAt" ] }, "slug": { "type": "string" }, "title": { "type": "string" } }, "required": [ "asin", "buyUrl", "found", "fresh", "imageUrl", "price", "priceFormatted", "priceFreshness", "slug", "title" ] }, { "type": "object", "properties": { "asin": { "type": "string" }, "buyUrl": { "type": "string" }, "found": { "type": "boolean" }, "fresh": { "type": "boolean" }, "imageUrl": { "type": "string", "nullable": true }, "price": { "type": "number" }, "priceFormatted": { "type": "string", "nullable": true }, "priceFreshness": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "refresh_error", "refresh_stale", "no_data", "no_trends", "source_unavailable" ], "nullable": true }, "staleAfterHours": { "type": "number" }, "status": { "type": "string", "enum": [ "fresh", "stale", "unavailable" ] }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "staleAfterHours", "status", "updatedAt" ] }, "slug": { "type": "string" }, "title": { "type": "string" } }, "required": [ "asin", "buyUrl", "found", "fresh", "imageUrl", "price", "priceFormatted", "priceFreshness", "slug", "title" ] }, { "type": "object", "properties": { "asin": { "type": "string" }, "buyUrl": { "type": "string" }, "found": { "type": "boolean" }, "fresh": { "type": "boolean" }, "imageUrl": { "type": "string", "nullable": true }, "priceFreshness": { "type": "object", "additionalProperties": true }, "slug": { "type": "string" }, "title": { "type": "string" } }, "required": [ "asin", "buyUrl", "found", "fresh", "imageUrl", "priceFreshness", "slug", "title" ] } ] }, "example": { "found": true, "message": "string", "slug": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "found": { "type": "boolean" } }, "required": [ "error", "found" ] }, "example": { "error": "string", "found": true } } } } }, "description": "Flow: 1. Check ASIN cache for this slug 2. If not cached, search Amazon by product name and cache the ASIN 3. Fetch fresh price from Amazon using the ASIN 4. Return price, buy URL, and image", "parameters": [ { "name": "name", "in": "query", "required": true, "description": "name parameter.", "schema": { "type": "string" } }, { "name": "slug", "in": "query", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ], "security": [ { "supabaseSession": [] } ] } }, "/api/amazon/refresh-prices": { "post": { "operationId": "postAmazonRefreshPrices", "summary": "Refresh cached Amazon prices", "tags": [ "amazon" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "updated": { "type": "number" } }, "required": [ "message", "updated" ] }, { "type": "object", "properties": { "amazonRowsExpired": { "type": "number" }, "amazonRowsRevived": { "type": "number" }, "dbInserted": { "type": "number" }, "failed": { "type": "number" }, "failedOosSlugs": { "type": "array", "items": { "type": "string" } }, "imagesBackfilled": { "type": "number" }, "imagesBackfillUnverified": { "type": "number" }, "lastRefreshStamped": { "type": "number" }, "message": { "type": "string" }, "parametricDrain": { "oneOf": [ { "type": "object", "properties": { "alertsRaised": { "type": "number" }, "batches": { "type": "number" }, "batchesHeld": { "type": "number" }, "candidateRowsRead": { "type": "number" }, "dryRun": { "type": "boolean" }, "elapsedMs": { "type": "number" }, "linesEvaluated": { "type": "number" }, "ran": { "type": "boolean" }, "source": { "type": "string" }, "winnersChanged": { "type": "number" } }, "required": [ "alertsRaised", "batches", "batchesHeld", "candidateRowsRead", "dryRun", "elapsedMs", "linesEvaluated", "ran", "source", "winnersChanged" ] }, { "type": "object", "additionalProperties": true } ] }, "parametricWakes": { "type": "number" }, "priceAlertEmailsSent": { "type": "number" }, "priceAlertsChecked": { "type": "number" }, "priceAlertsTriggered": { "type": "number" }, "revalidatedCategories": { "type": "number" }, "revalidatedProducts": { "type": "number" }, "salesRanksUpdated": { "type": "number" }, "skippedCondition": { "type": "number" }, "skippedPrice": { "type": "number" }, "stockAlertsSent": { "type": "number" }, "stockRestored": { "type": "number" }, "totalTracked": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "amazonRowsExpired", "amazonRowsRevived", "dbInserted", "failed", "failedOosSlugs", "imagesBackfillUnverified", "imagesBackfilled", "lastRefreshStamped", "message", "parametricDrain", "parametricWakes", "priceAlertEmailsSent", "priceAlertsChecked", "priceAlertsTriggered", "revalidatedCategories", "revalidatedProducts", "salesRanksUpdated", "skippedCondition", "skippedPrice", "stockAlertsSent", "stockRestored", "totalTracked", "updated" ] } ] }, "example": { "message": "string", "updated": 1 } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "amazonStatus": { "type": "number" }, "dbInserted": { "type": "number" }, "error": { "type": "string" }, "failed": { "type": "number" }, "message": { "type": "string" }, "parametricDrain": { "oneOf": [ { "type": "object", "properties": { "alertsRaised": { "type": "number" }, "batches": { "type": "number" }, "batchesHeld": { "type": "number" }, "candidateRowsRead": { "type": "number" }, "dryRun": { "type": "boolean" }, "elapsedMs": { "type": "number" }, "linesEvaluated": { "type": "number" }, "ran": { "type": "boolean" }, "source": { "type": "string" }, "winnersChanged": { "type": "number" } }, "required": [ "alertsRaised", "batches", "batchesHeld", "candidateRowsRead", "dryRun", "elapsedMs", "linesEvaluated", "ran", "source", "winnersChanged" ] }, { "type": "object", "additionalProperties": true } ] }, "parametricWakes": { "type": "number" }, "totalTracked": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "amazonStatus", "dbInserted", "error", "failed", "message", "parametricDrain", "parametricWakes", "totalTracked", "updated" ] }, "example": { "amazonStatus": 1, "dbInserted": 1, "error": "string", "failed": 1, "message": "string", "parametricDrain": { "alertsRaised": 1, "batches": 1, "batchesHeld": 1, "candidateRowsRead": 1, "dryRun": true, "elapsedMs": 1, "linesEvaluated": 1, "ran": true, "source": "string", "winnersChanged": 1 }, "parametricWakes": 1, "totalTracked": 1, "updated": 1 } } } } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Body: { batchSize?: number } 1. Reads known slug→ASIN mappings from asin_price_snapshots (DB) 2. Fetches fresh prices from Amazon (10 per API call) 3. Writes new price snapshots to Supabase (asin_price_snapshots table) 4. PLA-2832: fires on-demand ISR revalidation (revalidatePath) for exactly the PDPs whose displayed price changed, plus their category listings. Because the pg_cron round-robin (PLA-1793) POSTs to this Next.js route via pg_net, the handler has a request context and can revalidate in-process — the same pattern as the Rakuten cron. No hop to /api/internal/revalidate. Validates: condition, price sanity (no 3x swings). Scheduling: this write path is driven by Supabase pg_cron (configured in Supabase, not vercel.json — the vercel.json crons cover price-freshness-check, snapshot-coverage, and alerts/check only). Since PLA-1793 the pg_cron job `refresh-prices-every-2h` posts directly to this route (batchSize 1500, onlyMissing) — the legacy Supabase Edge Function `refresh-prices` is retired because its deployed copy drifted from the repo. The companion GET export below is an UNAUTHENTICATED public read for price history/stats; only this POST write path is CRON_SECRET-gated.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchSize": { "type": "integer", "minimum": 1 }, "onlyMissing": { "type": "string" } } }, "example": { "batchSize": 1, "onlyMissing": "string" } } } } }, "get": { "operationId": "getAmazonRefreshPrices", "summary": "Get Amazon price refresh status", "tags": [ "amazon" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "newestEntry": { "type": "string", "nullable": true }, "oldestEntry": { "type": "string", "nullable": true }, "totalEntries": { "type": "number" }, "totalProducts": { "type": "number" } }, "required": [ "newestEntry", "oldestEntry", "totalEntries", "totalProducts" ] }, { "type": "object", "properties": { "currentPrice": { "type": "number" }, "entries": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "highestPrice": { "type": "number", "nullable": true }, "lowestPrice": { "type": "number", "nullable": true }, "slug": { "type": "string" } }, "required": [ "currentPrice", "entries", "highestPrice", "lowestPrice", "slug" ] } ] }, "example": { "newestEntry": "string", "oldestEntry": "string", "totalEntries": 1, "totalProducts": 1 } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/amazon/refresh-prices`. Query params: `slug`.", "parameters": [ { "name": "slug", "in": "query", "required": false, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/analytics/affiliate-click": { "post": { "operationId": "postAnalyticsAffiliateClick", "summary": "Create affiliate click", "tags": [ "analytics" ], "responses": { "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/analytics/affiliate-click`." } }, "/api/analytics/events": { "post": { "operationId": "postAnalyticsEvents", "summary": "Create events", "tags": [ "analytics" ], "responses": { "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/analytics/events`." } }, "/api/analytics/web-vitals": { "post": { "operationId": "postAnalyticsWebVitals", "summary": "PUBLIC: anonymous, consent-gated RUM ingestion must be callable before a", "tags": [ "analytics" ], "responses": { "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "413": { "description": "HTTP 413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "user has an account. It is append-only, schema-bounded, rate-limited, bot-filtered, and stores no raw path, IP, user agent, cookie, or session ID." } }, "/api/auth/delete-account": { "delete": { "operationId": "deleteAuthDeleteAccount", "summary": "Delete the current user account", "tags": [ "auth" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/auth/delete-account`.", "security": [ { "supabaseSession": [] } ] } }, "/api/auth/forgot-password": { "post": { "operationId": "postAuthForgotPassword", "summary": "Create forgot password", "tags": [ "auth" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/auth/forgot-password`." } }, "/api/auth/login": { "post": { "operationId": "postAuthLogin", "summary": "Log in a user", "tags": [ "auth" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/auth/login`.", "security": [ { "supabaseSession": [] } ] } }, "/api/auth/logout": { "post": { "operationId": "postAuthLogout", "summary": "Log out the current user", "tags": [ "auth" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/auth/logout`.", "security": [ { "supabaseSession": [] } ] } }, "/api/auth/resend-verification": { "post": { "operationId": "postAuthResendVerification", "summary": "Resend the verification email", "tags": [ "auth" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/auth/resend-verification`." } }, "/api/auth/session": { "get": { "operationId": "getAuthSession", "summary": "no IDOR surface. No tokens are ever returned in the body", "tags": [ "auth" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/auth/session`.", "security": [ { "supabaseSession": [] } ] } }, "/api/auth/signup": { "post": { "operationId": "postAuthSignup", "summary": "Register a user", "tags": [ "auth" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/auth/signup`." } }, "/api/auth/verify": { "post": { "operationId": "postAuthVerify", "summary": "Verify a signup token", "tags": [ "auth" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/auth/verify`." } }, "/api/benchmarks": { "get": { "operationId": "getBenchmarks", "summary": "List benchmark data", "tags": [ "benchmarks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "scores": { "type": "array", "items": { "type": "object", "properties": { "manufacturer": { "type": "string" }, "price": { "type": "number" }, "productName": { "type": "string" }, "productSlug": { "type": "string" }, "score": { "type": "number" }, "suiteId": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "manufacturer", "price", "productName", "productSlug", "score" ] } }, "suite": { "type": "object", "properties": { "category": { "type": "string" }, "description": { "type": "string" }, "higherBetter": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "category", "description", "higherBetter", "id", "name", "slug", "unit" ] } }, "required": [ "scores", "suite" ] } } }, "required": [ "results" ] }, "example": { "results": [ { "scores": [ { "manufacturer": "string", "price": 1, "productName": "string", "productSlug": "string", "score": 1, "suiteId": {} } ], "suite": { "category": "string", "description": "string", "higherBetter": true, "id": "string", "name": "string", "slug": "string", "unit": "string" } } ] } } } } }, "description": "Auto-generated from the route handler for `/api/benchmarks`. Query params: `category`.", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category slug.", "schema": { "type": "string" } } ] } }, "/api/build/custom-metadata": { "post": { "operationId": "postBuildCustomMetadata", "summary": "Create custom metadata", "tags": [ "build" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "imageUrl": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "priceCents": { "type": "number", "nullable": true }, "sourceUrl": { "type": "string" }, "verifiable": { "type": "boolean" } }, "required": [ "sourceUrl", "verifiable" ] }, "example": { "imageUrl": "string", "name": "string", "priceCents": 1, "sourceUrl": "string", "verifiable": true } } } }, "422": { "description": "Unprocessable entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "fallback": { "type": "string" }, "reason": { "type": "string", "enum": [ "invalid_url", "bad_scheme", "blocked_address", "dns_no_records", "dns_failed", "too_many_redirects", "redirect_no_location", "http_error", "bad_content_type", "too_large", "timeout", "request_failed" ] } }, "required": [ "error", "fallback", "reason" ] }, "example": { "error": "string", "fallback": "string", "reason": "invalid_url" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "status": { "type": "number" } }, "required": [ "error", "status" ] }, "example": { "error": "string", "status": 1 } } } } }, "description": "Auto-generated from the route handler for `/api/build/custom-metadata`.", "security": [ { "supabaseSession": [] } ] } }, "/api/builds": { "get": { "operationId": "getBuilds", "summary": "List community builds", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "builds": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "limit": { "type": "number" }, "page": { "type": "number" }, "total": { "type": "number" } }, "required": [ "builds", "limit", "page", "total" ] }, "example": { "builds": [ {} ], "limit": 1, "page": 1, "total": 1 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds`. Query params: `maxPrice`, `minPrice`, `sort`, `useCase`, `userId`.", "parameters": [ { "name": "maxPrice", "in": "query", "required": false, "description": "Price filter or target value.", "schema": { "type": "number" } }, { "name": "minPrice", "in": "query", "required": false, "description": "Price filter or target value.", "schema": { "type": "number" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order.", "schema": { "type": "string" } }, { "name": "useCase", "in": "query", "required": false, "description": "useCase parameter.", "schema": { "type": "string" } }, { "name": "userId", "in": "query", "required": false, "description": "userId parameter.", "schema": { "type": "string" } } ], "security": [ { "supabaseSession": [] } ] }, "post": { "operationId": "postBuilds", "summary": "Create a build", "tags": [ "builds" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "avatarUrl": { "type": "string", "nullable": true }, "commentCount": { "type": "number" }, "comments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "cpuName": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } ] }, "gpuName": { "type": "string" }, "id": { "type": "string" }, "moderationStatus": { "type": "string", "enum": [ "PUBLISHED", "UNLISTED", "REMOVED" ] }, "parts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "photos": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "rating": { "type": "number" }, "ratingCount": { "type": "number" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "PUBLISHED", "DRAFT", "COMPLETED" ] }, "title": { "type": "string" }, "totalPrice": { "type": "number" }, "totalWattage": { "type": "number" }, "useCase": { "type": "string" }, "userId": { "type": "string" }, "username": { "type": "string" }, "viewCount": { "type": "number" } }, "required": [ "avatarUrl", "commentCount", "comments", "cpuName", "createdAt", "description", "gpuName", "id", "moderationStatus", "parts", "photos", "rating", "ratingCount", "slug", "status", "title", "totalPrice", "totalWattage", "useCase", "userId", "username", "viewCount" ] }, "example": { "avatarUrl": "string", "commentCount": 1, "comments": [ {} ], "cpuName": "string", "createdAt": "string", "description": "string", "gpuName": "string", "id": "string", "moderationStatus": "PUBLISHED", "parts": [ {} ], "photos": [ {} ], "rating": 1, "ratingCount": 1, "slug": "string", "status": "PUBLISHED", "title": "string", "totalPrice": 1, "totalWattage": 1, "useCase": "string", "userId": "string", "username": "string", "viewCount": 1 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "422": { "description": "Unprocessable entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "error", "fieldErrors" ] }, "example": { "error": "string", "fieldErrors": {} } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds`.", "security": [ { "supabaseSession": [] } ] } }, "/api/builds/{id}": { "get": { "operationId": "getBuildsId", "summary": "Get a build by id", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorReputation": { "type": "object", "properties": { "activity": { "type": "object", "properties": { "buildCommentsReceived": { "type": "number" }, "buildLikesReceived": { "type": "number" }, "buildsPublished": { "type": "number" }, "forumPosts": { "type": "number" }, "forumReplies": { "type": "number" }, "reviews": { "type": "number" } }, "required": [ "buildCommentsReceived", "buildLikesReceived", "buildsPublished", "forumPosts", "forumReplies", "reviews" ] }, "description": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "number" }, "tier": { "type": "string", "enum": [ "newcomer", "contributor", "regular", "trusted", "legend" ] } }, "required": [ "activity", "description", "label", "score", "tier" ] }, "avatarUrl": { "type": "string", "nullable": true }, "commentCount": { "type": "number" }, "comments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "cpuName": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "gpuName": { "type": "string" }, "id": { "type": "string" }, "likeCount": { "type": "number" }, "linkedDiscussion": { "type": "object", "additionalProperties": true, "nullable": true }, "parts": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "nullable": true }, "price": { "type": "number", "nullable": true }, "productId": { "type": "string", "nullable": true }, "productName": { "type": "string", "nullable": true }, "productSlug": { "type": "string", "nullable": true }, "quantity": { "type": "number", "nullable": true } } } }, "photos": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "slug": { "type": "string" }, "title": { "type": "string" }, "totalPrice": { "type": "number" }, "totalWattage": { "type": "number" }, "useCase": { "type": "string" }, "userId": { "type": "string" }, "username": { "type": "string" }, "viewCount": { "type": "number" } }, "required": [ "authorReputation", "avatarUrl", "commentCount", "comments", "cpuName", "createdAt", "description", "gpuName", "id", "likeCount", "linkedDiscussion", "parts", "photos", "slug", "title", "totalPrice", "totalWattage", "useCase", "userId", "username", "viewCount" ] }, "example": { "authorReputation": { "activity": { "buildCommentsReceived": 1, "buildLikesReceived": 1, "buildsPublished": 1, "forumPosts": 1, "forumReplies": 1, "reviews": 1 }, "description": "string", "label": "string", "score": 1, "tier": "newcomer" }, "avatarUrl": "string", "commentCount": 1, "comments": [ {} ], "cpuName": "string", "createdAt": "string", "description": "string", "gpuName": "string", "id": "string", "likeCount": 1, "linkedDiscussion": {}, "parts": [ { "category": "string", "price": 1, "productId": "string", "productName": "string", "productSlug": "string", "quantity": 1 } ], "photos": [ {} ], "slug": "string", "title": "string", "totalPrice": 1, "totalWattage": 1, "useCase": "string", "userId": "string", "username": "string", "viewCount": 1 } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] }, "put": { "operationId": "putBuildsId", "summary": "Update a build", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorReputation": { "type": "object", "properties": { "activity": { "type": "object", "properties": { "buildCommentsReceived": { "type": "number" }, "buildLikesReceived": { "type": "number" }, "buildsPublished": { "type": "number" }, "forumPosts": { "type": "number" }, "forumReplies": { "type": "number" }, "reviews": { "type": "number" } }, "required": [ "buildCommentsReceived", "buildLikesReceived", "buildsPublished", "forumPosts", "forumReplies", "reviews" ] }, "description": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "number" }, "tier": { "type": "string", "enum": [ "newcomer", "contributor", "regular", "trusted", "legend" ] } }, "required": [ "activity", "description", "label", "score", "tier" ] }, "avatarUrl": { "type": "string", "nullable": true }, "commentCount": { "type": "number" }, "comments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "cpuName": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "gpuName": { "type": "string" }, "id": { "type": "string" }, "likeCount": { "type": "number" }, "linkedDiscussion": { "type": "object", "additionalProperties": true, "nullable": true }, "parts": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "nullable": true }, "price": { "type": "number", "nullable": true }, "productId": { "type": "string", "nullable": true }, "productName": { "type": "string", "nullable": true }, "productSlug": { "type": "string", "nullable": true }, "quantity": { "type": "number", "nullable": true } } } }, "photos": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "slug": { "type": "string" }, "title": { "type": "string" }, "totalPrice": { "type": "number" }, "totalWattage": { "type": "number" }, "useCase": { "type": "string" }, "userId": { "type": "string" }, "username": { "type": "string" }, "viewCount": { "type": "number" } }, "required": [ "authorReputation", "avatarUrl", "commentCount", "comments", "cpuName", "createdAt", "description", "gpuName", "id", "likeCount", "linkedDiscussion", "parts", "photos", "slug", "title", "totalPrice", "totalWattage", "useCase", "userId", "username", "viewCount" ] }, "example": { "authorReputation": { "activity": { "buildCommentsReceived": 1, "buildLikesReceived": 1, "buildsPublished": 1, "forumPosts": 1, "forumReplies": 1, "reviews": 1 }, "description": "string", "label": "string", "score": 1, "tier": "newcomer" }, "avatarUrl": "string", "commentCount": 1, "comments": [ {} ], "cpuName": "string", "createdAt": "string", "description": "string", "gpuName": "string", "id": "string", "likeCount": 1, "linkedDiscussion": {}, "parts": [ { "category": "string", "price": 1, "productId": "string", "productName": "string", "productSlug": "string", "quantity": 1 } ], "photos": [ {} ], "slug": "string", "title": "string", "totalPrice": 1, "totalWattage": 1, "useCase": "string", "userId": "string", "username": "string", "viewCount": 1 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] }, "delete": { "operationId": "deleteBuildsId", "summary": "Delete a build", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] }, "example": { "success": true } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] }, "patch": { "operationId": "patchBuildsId", "summary": "Partially update a build", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "likeCount": { "type": "number" }, "liked": { "type": "boolean" } }, "required": [ "likeCount", "liked" ] }, "example": { "likeCount": 1, "liked": true } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/builds/{id}/clone": { "get": { "operationId": "getBuildsIdClone", "summary": "PLA-3230 (S2 of PLA-3178) — `GET /api/builds/[id]/clone` (AC3)", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "buildId": { "type": "string" }, "buildSlug": { "type": "string" }, "buildTitle": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "CPU", "CPU_COOLER", "MOTHERBOARD", "MEMORY", "STORAGE", "VIDEO_CARD", "CASE", "POWER_SUPPLY", "OPERATING_SYSTEM", "MONITOR", "KEYBOARD", "MOUSE", "HEADSET", "SPEAKERS", "WEBCAM", "CASE_FAN", "NETWORK", "OPTICAL_DRIVE", "GAMING_CHAIR", "DESK", "MOUSEPAD", "MICROPHONE", "STREAM_DECK", "CAPTURE_CARD", "VR_HEADSET", "CONTROLLER", "LIGHTING", "UPS", "EXTERNAL_STORAGE", "AUDIO_INTERFACE", "SIM_RACING", "CABLE_MANAGEMENT" ] }, "lineId": { "type": "string" }, "order": { "type": "number" }, "product": { "type": "object", "properties": { "asin": { "type": "object", "additionalProperties": true, "nullable": true }, "avgRating": { "type": "number" }, "category": { "type": "string", "enum": [ "CPU", "CPU_COOLER", "MOTHERBOARD", "MEMORY", "STORAGE", "VIDEO_CARD", "CASE", "POWER_SUPPLY", "OPERATING_SYSTEM", "MONITOR", "KEYBOARD", "MOUSE", "HEADSET", "SPEAKERS", "WEBCAM", "CASE_FAN", "NETWORK", "OPTICAL_DRIVE", "GAMING_CHAIR", "DESK", "MOUSEPAD", "MICROPHONE", "STREAM_DECK", "CAPTURE_CARD", "VR_HEADSET", "CONTROLLER", "LIGHTING", "UPS", "EXTERNAL_STORAGE", "AUDIO_INTERFACE", "SIM_RACING", "CABLE_MANAGEMENT" ] }, "discontinued": { "type": "boolean" }, "id": { "type": "string" }, "imageUrl": { "type": "object", "additionalProperties": true, "nullable": true }, "manufacturerSlug": { "type": "string" }, "name": { "type": "string" }, "prices": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "priceUsd": { "type": "object", "additionalProperties": true, "nullable": true }, "reviewCount": { "type": "number" }, "slug": { "type": "string" }, "specs": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } }, "tdp": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "asin", "avgRating", "category", "discontinued", "id", "imageUrl", "manufacturerSlug", "name", "priceUsd", "prices", "reviewCount", "slug", "specs", "tdp" ], "nullable": true }, "quantity": { "type": "number" }, "reason": { "type": "string", "enum": [ "discontinued", "not_in_catalog", "custom_part", "ambiguous_name" ], "nullable": true }, "replacedFrom": { "type": "object", "properties": { "productId": { "type": "object", "additionalProperties": true, "nullable": true }, "productName": { "type": "object", "additionalProperties": true, "nullable": true }, "productSlug": { "type": "object", "additionalProperties": true, "nullable": true }, "provenance": { "type": "string", "enum": [ "custom", "catalog" ] } }, "required": [ "provenance" ], "nullable": true }, "replacementSource": { "type": "string", "enum": [ "author_substitution" ], "nullable": true }, "requested": { "type": "object", "properties": { "productId": { "type": "string", "nullable": true }, "productName": { "type": "string", "nullable": true }, "productSlug": { "type": "string", "nullable": true }, "provenance": { "type": "string", "enum": [ "custom", "catalog" ] } }, "required": [ "provenance" ] }, "status": { "type": "string", "enum": [ "unavailable", "available", "replaced" ] } }, "required": [ "category", "lineId", "order", "quantity", "requested", "status" ] } }, "source": { "type": "object", "properties": { "capturedAt": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "snapshot", "live" ] }, "label": { "type": "string", "nullable": true }, "snapshotId": { "type": "string", "nullable": true }, "version": { "type": "number", "nullable": true } }, "required": [ "kind" ] }, "summary": { "type": "object", "properties": { "available": { "type": "number" }, "hasIssues": { "type": "boolean" }, "replaced": { "type": "number" }, "total": { "type": "number" }, "unavailable": { "type": "number" } }, "required": [ "available", "hasIssues", "replaced", "total", "unavailable" ] }, "truncated": { "type": "object", "properties": { "returned": { "type": "number" }, "sourceLineCount": { "type": "number" } }, "required": [ "returned", "sourceLineCount" ], "nullable": true } }, "required": [ "buildId", "buildSlug", "buildTitle", "lines", "source", "summary" ] }, "example": { "buildId": "string", "buildSlug": "string", "buildTitle": "string", "lines": [ { "category": "CPU", "lineId": "string", "order": 1, "product": { "asin": {}, "avgRating": 1, "category": "CPU", "discontinued": true, "id": "string", "imageUrl": {}, "manufacturerSlug": "string", "name": "string", "prices": [ {} ], "priceUsd": {}, "reviewCount": 1, "slug": "string", "specs": {}, "tdp": {} }, "quantity": 1, "reason": "discontinued", "replacedFrom": { "productId": {}, "productName": {}, "productSlug": {}, "provenance": "custom" }, "replacementSource": "author_substitution", "requested": { "productId": "string", "productName": "string", "productSlug": "string", "provenance": "custom" }, "status": "unavailable" } ], "source": { "capturedAt": "string", "kind": "snapshot", "label": "string", "snapshotId": "string", "version": 1 }, "summary": { "available": 1, "hasIssues": true, "replaced": 1, "total": 1, "unavailable": 1 }, "truncated": { "returned": 1, "sourceLineCount": 1 } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Returns the **clone plan** for a published build: one entry per line of the build's immutable configuration snapshot, each resolved against the live catalog and labelled `available` / `replaced` / `unavailable`. The client adds the resolved products to the builder and shows the rest — nothing is dropped silently (see `src/lib/build/clone.ts` for why that mattered). Read-only: cloning creates nothing server-side, so this is a GET and there is no POST. The caller's own build is written by the existing builder save path. Privacy boundary: the lookup is gated on `cloneSourceWhere`, which is stricter than the build-detail gate — a draft or unlisted build is clonable by its author alone and a removed build by nobody. Journal bodies, photos and measured results are not part of this payload at all; the only journal-derived data that can reach it is a substitution on a PUBLISHED entry, used solely to rescue a line whose part has left the catalog. Query params: `?snapshot=` — clone a specific snapshot of this build instead of the latest. Scoped to the build, so a snapshot id belonging to another build resolves to nothing and 404s rather than leaking across builds.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } }, { "name": "snapshot", "in": "query", "required": false, "description": "snapshot parameter.", "schema": { "type": "string" } } ] } }, "/api/builds/{id}/journal": { "get": { "operationId": "getBuildsIdJournal", "summary": "List journal", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "buildId": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "authorId": { "type": "string" }, "body": { "type": "string" }, "buildId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "STEP", "NOTE", "UPDATE" ] }, "moderationStatus": { "type": "string", "enum": [ "PUBLISHED", "UNLISTED", "REMOVED" ] }, "order": { "type": "number" }, "snapshotId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "authorId", "body", "buildId", "createdAt", "id", "kind", "moderationStatus", "order", "snapshotId", "title", "updatedAt" ] } }, "total": { "type": "number" } }, "required": [ "buildId", "entries", "total" ] }, "example": { "buildId": "string", "entries": [ { "authorId": "string", "body": "string", "buildId": "string", "createdAt": "2026-04-10T12:00:00.000Z", "id": "string", "kind": "STEP", "moderationStatus": "PUBLISHED", "order": 1, "snapshotId": "string", "title": "string", "updatedAt": "2026-04-10T12:00:00.000Z" } ], "total": 1 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}/journal`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] }, "post": { "operationId": "postBuildsIdJournal", "summary": "Create journal", "tags": [ "builds" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "authorId": { "type": "string" }, "body": { "type": "string" }, "buildId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "STEP", "NOTE", "UPDATE" ] }, "moderationStatus": { "type": "string", "enum": [ "PUBLISHED", "UNLISTED", "REMOVED" ] }, "order": { "type": "number" }, "snapshotId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "authorId", "body", "buildId", "createdAt", "id", "kind", "moderationStatus", "order", "snapshotId", "title", "updatedAt" ] }, "moderation": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "entry" ] }, "example": { "entry": { "authorId": "string", "body": "string", "buildId": "string", "createdAt": "2026-04-10T12:00:00.000Z", "id": "string", "kind": "STEP", "moderationStatus": "PUBLISHED", "order": 1, "snapshotId": "string", "title": "string", "updatedAt": "2026-04-10T12:00:00.000Z" }, "moderation": {} } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}/journal`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/builds/{id}/journal/{entryId}": { "patch": { "operationId": "patchBuildsIdJournalEntryId", "summary": "PLA-3235 (S1b of PLA-3226) — edit/delete a single build journal entry (AC2)", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "authorId": { "type": "string" }, "body": { "type": "string" }, "buildId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "STEP", "NOTE", "UPDATE" ] }, "moderationStatus": { "type": "string", "enum": [ "PUBLISHED", "UNLISTED", "REMOVED" ] }, "order": { "type": "number" }, "snapshotId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "authorId", "body", "buildId", "createdAt", "id", "kind", "moderationStatus", "order", "snapshotId", "title", "updatedAt" ] }, "moderation": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "entry" ] }, "example": { "entry": { "authorId": "string", "body": "string", "buildId": "string", "createdAt": "2026-04-10T12:00:00.000Z", "id": "string", "kind": "STEP", "moderationStatus": "PUBLISHED", "order": 1, "snapshotId": "string", "title": "string", "updatedAt": "2026-04-10T12:00:00.000Z" }, "moderation": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "- `PATCH /api/builds/[id]/journal/[entryId]` — partial update. Nested photo / substitution / result collections are *replace-if-present*: omit a key to leave it untouched, send `[]` to clear it. - `DELETE /api/builds/[id]/journal/[entryId]` — remove the entry (its photos, substitutions and results cascade / detach per schema). Author-only, and the entry must belong to the build in the path — an entry id from another build 404s rather than being edited through a build the caller happens to own (IDOR). The attached configuration snapshot is immutable: a PATCH can re-point an entry at a different snapshot of the same build, but never rewrites one.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } }, { "name": "entryId", "in": "path", "required": true, "description": "entryId parameter.", "schema": { "type": "string" } } ] }, "delete": { "operationId": "deleteBuildsIdJournalEntryId", "summary": "Delete journal", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "deleted", "id" ] }, "example": { "deleted": true, "id": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}/journal/{entryId}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } }, { "name": "entryId", "in": "path", "required": true, "description": "entryId parameter.", "schema": { "type": "string" } } ] } }, "/api/builds/{id}/journal/{entryId}/report": { "post": { "operationId": "postBuildsIdJournalEntryIdReport", "summary": "PLA-4602 (S2b of PLA-3178, AC5) — report a journal entry, or one measured", "tags": [ "builds" ], "responses": { "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "result inside it. `POST /api/builds/[id]/journal/[entryId]/report`. Body is the shared report schema plus an optional `resultId`: pass it to report a single `BuildResult` (the \"this number is presented as more than it is\" case AC5 exists for) instead of the whole entry. Visibility mirrors `GET /api/builds/[id]/journal` exactly: the build must be readable, and the entry must be PUBLISHED unless the caller is the build's author. Anything else 404s — a 403 would confirm that a moderation-hidden entry exists.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } }, { "name": "entryId", "in": "path", "required": true, "description": "entryId parameter.", "schema": { "type": "string" } } ] } }, "/api/builds/{id}/like-status": { "get": { "operationId": "getBuildsIdLikeStatus", "summary": "Get the like status for a build", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "liked": { "type": "boolean" } }, "required": [ "liked" ] }, "example": { "liked": true } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}/like-status`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/builds/{id}/publish": { "post": { "operationId": "postBuildsIdPublish", "summary": "PLA-2448 — Publish a saved build to the public community listing", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "alreadyPublished": { "type": "boolean" }, "slug": { "type": "string" } }, "required": [ "alreadyPublished", "slug" ] }, "example": { "alreadyPublished": true, "slug": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "422": { "description": "Unprocessable entity", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string" }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "error", "fieldErrors" ] }, { "type": "object", "properties": { "error": { "type": "string" }, "fieldErrors": { "type": "object", "additionalProperties": true } }, "required": [ "error", "fieldErrors" ] } ] }, "example": { "error": "string", "fieldErrors": {} } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Saving a build (POST /api/builds with status=DRAFT) keeps it private to the owner. This endpoint is the explicit \"Publish to community\" action: it flips the build to `status=COMPLETED` + `moderationStatus=PUBLISHED` so it shows in `/builds`, but only after the same min-quality gate the create path enforces (descriptive title, CPU + GPU present) and the anti-spam heuristic. Ownership is required — a build can only be published by its author.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/builds/{id}/rating": { "get": { "operationId": "getBuildsIdRating", "summary": "List rating", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "number" }, "ratingCount": { "type": "number" }, "userRating": { "type": "number", "nullable": true } }, "required": [ "rating", "ratingCount", "userRating" ] }, "example": { "rating": 1, "ratingCount": 1, "userRating": 1 } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}/rating`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] }, "post": { "operationId": "postBuildsIdRating", "summary": "Create rating", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "number" }, "ratingCount": { "type": "number" }, "userRating": { "type": "number" } }, "required": [ "rating", "ratingCount", "userRating" ] }, "example": { "rating": 1, "ratingCount": 1, "userRating": 1 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}/rating`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/builds/{id}/report": { "post": { "operationId": "postBuildsIdReport", "summary": "PLA-4602 (S2b of PLA-3178, AC5) — report a build", "tags": [ "builds" ], "responses": { "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "`POST /api/builds/[id]/report` — open to signed-in and anonymous reporters alike (abuse reporting that requires an account is abuse reporting nobody files), rate limited per identity and deduped per (reporter, target) by a database constraint. The build is resolved through `loadBuildForRead`, the same gate the build detail and journal reads use. A build the caller cannot see therefore 404s here exactly as it would there — reporting must never be an existence oracle for drafts or removed content.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/builds/{id}/snapshots": { "get": { "operationId": "getBuildsIdSnapshots", "summary": "List snapshots", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}/snapshots`. Query params: `includeDoc`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } }, { "name": "includeDoc", "in": "query", "required": false, "description": "includeDoc parameter.", "schema": { "type": "string" } } ] }, "post": { "operationId": "postBuildsIdSnapshots", "summary": "Create snapshots", "tags": [ "builds" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshot": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "snapshot" ] }, "example": { "snapshot": {} } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/{id}/snapshots`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/builds/discover": { "get": { "operationId": "getBuildsDiscover", "summary": "List discover", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "builds": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "filters": { "type": "object", "additionalProperties": true }, "limit": { "type": "number" }, "page": { "type": "number" }, "total": { "type": "number" } }, "required": [ "builds", "filters", "limit", "page", "total" ] }, "example": { "builds": [ {} ], "filters": {}, "limit": 1, "page": 1, "total": 1 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/discover`. Query params: `category`, `currency`, `maxPrice`, `minPrice`, `minRating`, `productId`, `productSlug`, `since`, `sort`, `useCase`.", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category slug.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "currency parameter.", "schema": { "type": "string" } }, { "name": "maxPrice", "in": "query", "required": false, "description": "Price filter or target value.", "schema": { "type": "number" } }, { "name": "minPrice", "in": "query", "required": false, "description": "Price filter or target value.", "schema": { "type": "number" } }, { "name": "minRating", "in": "query", "required": false, "description": "minRating parameter.", "schema": { "type": "number", "minimum": 0 } }, { "name": "productId", "in": "query", "required": false, "description": "productId parameter.", "schema": { "type": "string" } }, { "name": "productSlug", "in": "query", "required": false, "description": "productSlug parameter.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "since parameter.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order.", "schema": { "type": "string" } }, { "name": "useCase", "in": "query", "required": false, "description": "useCase parameter.", "schema": { "type": "string" } } ] } }, "/api/builds/photo": { "post": { "operationId": "postBuildsPhoto", "summary": "authenticated build-photo upload", "tags": [ "builds" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, "example": { "url": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Background (PLA-1811, follow-up to PLA-1799): the `build-photos` storage bucket has RLS enabled with NO insert policy, so neither the anon nor the authenticated role can write objects via the client SDK — every client-side upload returns \"new row violates row-level security policy\". (PLA-1799 also made the session cookie HttpOnly, so the browser client no longer even carries the user JWT.) This route moves the upload server-side: it authenticates the caller via the HttpOnly session, then performs the write with the service-role admin client, which bypasses RLS. The bucket stays locked down to clients (no direct write access) and uploads are gated on a real authenticated session.", "security": [ { "supabaseSession": [] } ] } }, "/api/builds/share": { "post": { "operationId": "postBuildsShare", "summary": "Create a public share link for a build", "tags": [ "builds" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiUrl": { "type": "string" }, "shareUrl": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "apiUrl", "shareUrl", "slug" ] }, "example": { "apiUrl": "string", "shareUrl": "string", "slug": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/share`. This operation accepts a JSON request body.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "productName": { "type": "string" }, "price": { "type": "number" } } } }, "title": { "type": "string" } } }, "example": { "parts": [ { "category": "string", "productName": "string", "price": 1 } ], "title": "string" } } } } } }, "/api/builds/share/{slug}": { "get": { "operationId": "getBuildsShareSlug", "summary": "Get a shared build by slug", "tags": [ "builds" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "createdAt": { "type": "string" }, "parts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "shareUrl": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string", "nullable": true }, "totalPrice": { "type": "number" }, "viewCount": { "type": "number" } }, "required": [ "createdAt", "parts", "shareUrl", "slug", "title", "totalPrice", "viewCount" ] }, "example": { "createdAt": "string", "parts": [ {} ], "shareUrl": "string", "slug": "string", "title": "string", "totalPrice": 1, "viewCount": 1 } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/builds/share/{slug}`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/catalog-proposals": { "post": { "operationId": "postCatalogProposals", "summary": "Create catalog proposals", "tags": [ "catalog-proposals" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/catalog-proposals`." } }, "/api/catalog-proposals/{id}/evidence": { "post": { "operationId": "postCatalogProposalsIdEvidence", "summary": "Create evidence", "tags": [ "catalog-proposals" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/catalog-proposals/{id}/evidence`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ] } }, "/api/catalog-proposals/{id}/source-preview": { "post": { "operationId": "postCatalogProposalsIdSourcePreview", "summary": "Create source preview", "tags": [ "catalog-proposals" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/catalog-proposals/{id}/source-preview`. Query params: `evidenceId`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } }, { "name": "evidenceId", "in": "query", "required": false, "description": "evidenceId parameter.", "schema": { "type": "string" } } ] } }, "/api/catalog-proposals/dup-check": { "get": { "operationId": "getCatalogProposalsDupCheck", "summary": "List dup check", "tags": [ "catalog-proposals" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/catalog-proposals/dup-check`." } }, "/api/catalog-proposals/mine": { "get": { "operationId": "getCatalogProposalsMine", "summary": "List mine", "tags": [ "catalog-proposals" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/catalog-proposals/mine`." } }, "/api/catalog-proposals/notifications/read": { "post": { "operationId": "postCatalogProposalsNotificationsRead", "summary": "Create read", "tags": [ "catalog-proposals" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/catalog-proposals/notifications/read`." } }, "/api/catalog-proposals/promote-custom-part": { "post": { "operationId": "postCatalogProposalsPromoteCustomPart", "summary": "Create promote custom part", "tags": [ "catalog-proposals" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/catalog-proposals/promote-custom-part`." } }, "/api/ci/preview-lighthouse": { "post": { "operationId": "postCiPreviewLighthouse", "summary": "Create preview lighthouse", "tags": [ "ci" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deploymentUrl": { "type": "string" }, "status": { "type": "string" } }, "required": [ "deploymentUrl", "status" ] }, "example": { "deploymentUrl": "string", "status": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "422": { "description": "Unprocessable entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/ci/preview-lighthouse`." } }, "/api/comments": { "post": { "operationId": "postComments", "summary": "Create a build comment", "tags": [ "comments" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "avatarUrl": { "type": "string", "nullable": true }, "body": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "parentId": { "type": "string", "nullable": true }, "userId": { "type": "string" }, "username": { "type": "string" } }, "required": [ "avatarUrl", "body", "createdAt", "id", "parentId", "userId", "username" ] }, "example": { "avatarUrl": "string", "body": "string", "createdAt": "string", "id": "string", "parentId": "string", "userId": "string", "username": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/comments`.", "security": [ { "supabaseSession": [] } ] } }, "/api/compatibility": { "post": { "operationId": "postCompatibility", "summary": "Check compatibility for selected parts", "tags": [ "compatibility" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "compatible": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string" }, "parts": { "type": "array", "items": { "type": "string" } } }, "required": [ "level", "message", "parts" ] } }, "report": { "type": "object", "properties": { "coverage": { "type": "object", "properties": { "familiesEvaluated": { "type": "number" }, "familiesNotVerifiable": { "type": "number" }, "familiesTotal": { "type": "number" }, "unknownFieldRate": { "type": "number" } }, "required": [ "familiesEvaluated", "familiesNotVerifiable", "familiesTotal", "unknownFieldRate" ] }, "engineVersion": { "type": "number", "enum": [ 2 ] }, "overall": { "type": "string", "enum": [ "issues", "compatible", "not_verifiable" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "affectedLineIds": { "type": "array", "items": { "type": "string" } }, "detail": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "object", "additionalProperties": true }, "partCategory": { "type": "object", "additionalProperties": true }, "unit": { "type": "object", "additionalProperties": true }, "value": { "type": "object", "additionalProperties": true } }, "required": [ "field", "partCategory", "value" ] } }, "family": { "type": "string", "enum": [ "cpu_platform", "memory", "clearance", "power", "storage", "cooling", "connectivity", "platform" ] }, "missingFields": { "type": "array", "items": { "type": "string" } }, "outcome": { "type": "string", "enum": [ "compatible", "not_verifiable", "issue", "warning" ] }, "provenance": { "type": "object", "properties": { "confidence": { "type": "string", "enum": [ "high", "medium" ] }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "source": { "type": "string", "enum": [ "normalized_spec", "catalog_field", "derived" ] } }, "required": [ "confidence", "fields", "source" ] }, "ruleId": { "type": "string", "enum": [ "cpu_socket", "cpu_chipset_support", "mem_type", "mem_capacity", "mem_modules", "mem_speed_support", "mem_ecc_registered", "mem_voltage", "gpu_length", "gpu_slot_thickness", "gpu_power_connectors", "psu_wattage", "psu_form_factor", "storage_m2_slot", "storage_lane_sharing", "cooler_socket", "cooler_height", "cooler_tdp", "cooler_radiator_mount", "mb_case_form_factor", "case_front_panel", "os_tpm", "build_quantity_support" ] }, "ruleVersion": { "type": "number" }, "severity": { "type": "string", "enum": [ "unknown", "warning", "blocker", "info" ] }, "title": { "type": "string" } }, "required": [ "affectedLineIds", "detail", "evidence", "family", "missingFields", "outcome", "provenance", "ruleId", "ruleVersion", "severity", "title" ] } } }, "required": [ "coverage", "engineVersion", "overall", "results" ] } }, "required": [ "compatible", "issues", "report" ] }, "example": { "compatible": true, "issues": [ { "level": "error", "message": "string", "parts": [ "string" ] } ], "report": { "coverage": { "familiesEvaluated": 1, "familiesNotVerifiable": 1, "familiesTotal": 1, "unknownFieldRate": 1 }, "engineVersion": 2, "overall": "issues", "results": [ { "affectedLineIds": [ "string" ], "detail": "string", "evidence": [ { "field": {}, "partCategory": {}, "unit": {}, "value": {} } ], "family": "cpu_platform", "missingFields": [ "string" ], "outcome": "compatible", "provenance": { "confidence": "high", "fields": [ {} ], "source": "normalized_spec" }, "ruleId": "cpu_socket", "ruleVersion": 1, "severity": "unknown", "title": "string" } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/compatibility`." } }, "/api/consent": { "post": { "operationId": "postConsent", "summary": "Create consent", "tags": [ "consent" ], "responses": { "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/consent`." } }, "/api/contact": { "post": { "operationId": "postContact", "summary": "Submit a contact form message", "tags": [ "contact" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] }, "example": { "success": true } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/contact`." } }, "/api/cron/abandoned-build-drip": { "post": { "operationId": "postCronAbandonedBuildDrip", "summary": "Create abandoned build drip", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/cron/abandoned-build-drip`." }, "get": { "operationId": "getCronAbandonedBuildDrip", "summary": "List abandoned build drip", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/cron/abandoned-build-drip`." } }, "/api/cron/affiliate-revenue-report": { "get": { "operationId": "getCronAffiliateRevenueReport", "summary": "PLA-2021 — weekly affiliate clicks/revenue rollup", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Runs weekly (Mon 07:00 UTC, after the price syncs). Computes the legacy trailing-7d click rollup plus the protected first-party growth report added by PLA-3286 (funnel, PDP experiment, newsletter, consent-observed MAU), and emits BOTH: 1. a structured JSON line in Vercel Function logs (archival), and 2. the formatted markdown report (in the response body) that the Data Engineer agent posts as the recurring comment on PLA-2021. There is no first-party Paperclip write path from prod, so the cron does not post the comment itself — it produces the report; the agent relays it." } }, "/api/cron/bestbuy-price-sync": { "get": { "operationId": "getCronBestbuyPriceSync", "summary": "PLA-3046 (parent PLA-3039) — demand-driven Best Buy price-sync sweep", "tags": [ "cron" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "status": { "type": "string" } }, "required": [ "reason", "status" ] }, "example": { "reason": "string", "status": "string" } } } } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Sweeps the full Product table in id-ordered chunks, and for each product that lacks a Best Buy ProductPrice, looks it up on the Best Buy Products API by an EXACT key (UPC → modelNumber/MPN → strict brand+model name search) and upserts a Best Buy ProductPrice when a HIGH-CONFIDENCE match is confirmed. Low- confidence name fallbacks are rejected (that is what capped Rakuten at ~15%, PLA-1962). --- Key-gated no-op --- Until DevOps provisions BESTBUY_API_KEY (PLA-3045), this route is a safe no-op: it returns `{ status: \"skipped\" }` without touching the DB, so it can be merged + scheduled ahead of the key without side effects. --- Provable < 300s completion --- Bounded two ways: a chunk ceiling (BESTBUY_PRICESYNC_CHUNK products/run) and a wall-clock budget (BESTBUY_PRICESYNC_WALL_CLOCK_BUDGET_MS = 240s, 60s under the function ceiling). Between API calls we pace by BESTBUY_PRICESYNC_REQUEST_SPACING_MS to respect Best Buy's rate limits (exact caps recorded by DevOps on PLA-3045). --- Forward progress --- An IngestionState row keyed BESTBUY_PRICESYNC_STATE_KEY tracks an id cursor. We page `id > cursor` ascending; when a chunk drains fully AND returns fewer than the ceiling, the pass is COMPLETE and the cursor resets so the next run starts fresh (picking up new products + retrying previously-unmatched ones). Query params (optional): ?dryRun=1 (report, write nothing), ?limit=N (smaller chunk for probing)." } }, "/api/cron/build-line-index-coverage": { "get": { "operationId": "getCronBuildLineIndexCoverage", "summary": "PLA-4501 — scheduled detector for the PLA-4421 class: build part lines that", "tags": [ "cron" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "builds": { "type": "number" }, "buildsIndexed": { "type": "number" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "belowBar": { "type": "boolean" }, "category": { "type": "string" }, "coveragePct": { "type": "number" }, "discoverable": { "type": "number" }, "gap": { "type": "number" }, "isDoD": { "type": "boolean" }, "present": { "type": "number" } }, "required": [ "belowBar", "category", "coveragePct", "discoverable", "gap", "isDoD", "present" ] } }, "checkedAt": { "type": "string" }, "emailDelivered": { "type": "boolean", "nullable": true }, "failures": { "type": "array", "items": { "type": "object", "properties": { "belowBar": { "type": "boolean" }, "category": { "type": "string" }, "coveragePct": { "type": "number" }, "discoverable": { "type": "number" }, "gap": { "type": "number" }, "isDoD": { "type": "boolean" }, "present": { "type": "number" } }, "required": [ "belowBar", "category", "coveragePct", "discoverable", "gap", "isDoD", "present" ] } }, "indexRows": { "type": "number" }, "minCoverage": { "type": "number" }, "pass": { "type": "boolean" }, "status": { "type": "string" } }, "required": [ "builds", "buildsIndexed", "categories", "checkedAt", "failures", "indexRows", "minCoverage", "pass", "status" ] }, "example": { "builds": 1, "buildsIndexed": 1, "categories": [ { "belowBar": true, "category": "string", "coveragePct": 1, "discoverable": 1, "gap": 1, "isDoD": true, "present": 1 } ], "checkedAt": "string", "emailDelivered": true, "failures": [ { "belowBar": true, "category": "string", "coveragePct": 1, "discoverable": 1, "gap": 1, "isDoD": true, "present": 1 } ], "indexRows": 1, "minCoverage": 1, "pass": true, "status": "string" } } } } }, "description": "fail catalog identity resolution and therefore never enter `build_line_index`, making exact-component discovery silently empty. Auth: Authorization: Bearer $CRON_SECRET Scheduled in vercel.json at \"0 8 * * *\" (daily). Why this exists: PLA-4436 shipped the measurement as a CLI gate (`scripts/build-line-index-coverage.ts`), but a script nobody runs is not a detector. The gap it measures is precisely the kind that stays invisible — PLA-4421's 71% line-drop passed three green sub-slices because every check reported build volume rather than line resolution. This route runs the SAME function the CLI runs (`computeLineIndexCoverage`), so the two cannot drift. Optional `?min=` overrides the coverage bar for ad-hoc probing; the schedule uses the PLA-4421 DoD default of 90%.", "parameters": [ { "name": "min", "in": "query", "required": false, "description": "min parameter.", "schema": { "type": "string" } } ] } }, "/api/cron/catalog-ingestion-benq": { "get": { "operationId": "getCronCatalogIngestionBenq", "summary": "PLA-1806 — weekly BenQ + Zowie (CJ adv 7236824) catalog ingestion", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Query: ?dryRun=1 — compute outcomes without writing. Chunked across invocations via the IngestionState row (slug \"benq\"). Scheduled Sundays 05:00 UTC (see vercel.json)." } }, "/api/cron/catalog-ingestion-hp": { "get": { "operationId": "getCronCatalogIngestionHp", "summary": "PLA-1806 — weekly HP US (CJ adv 6870053) catalog ingestion", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Query: ?dryRun=1 — compute outcomes without writing. Chunked across invocations via the IngestionState row (slug \"hp\"). Scheduled Sundays 04:00 UTC (see vercel.json)." } }, "/api/cron/catalog-ingestion-newegg": { "get": { "operationId": "getCronCatalogIngestionNewegg", "summary": "PLA-1864 — DEPRECATED. The supply-driven Newegg catalog sweep (Rakuten", "tags": [ "cron" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "example": { "status": "string" } } } } }, "description": "keyword discovery, PLA-1805) is retired in favor of the demand-driven price-sync at `/api/cron/rakuten-price-sync`, which looks up a Newegg price per existing Product rather than crawling the whole advertiser catalog. This route is intentionally inert: it no longer ingests anything and has been removed from `vercel.json` crons. It is kept in place (returning a stable `deprecated` marker) so any lingering external caller or cached schedule gets a clean 200 instead of a 404 while the deprecation propagates. PUBLIC: does no work, reads/writes nothing, exposes no data — no auth needed. PLA-2790: the \"wrap every scheduled route in try/catch\" hardening is N/A here — the handler is a single synchronous `NextResponse.json(...)` with no async work, DB, or I/O that could throw, so a try/catch would be dead code." } }, "/api/cron/catalog-ingestion-steelseries": { "get": { "operationId": "getCronCatalogIngestionSteelseries", "summary": "PLA-1806 — weekly SteelSeries (CJ adv 7263737) catalog ingestion", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Query: ?dryRun=1 — compute outcomes without writing. Chunked across invocations via the IngestionState row (slug \"steelseries\"). Scheduled Sundays 03:00 UTC (see vercel.json)." } }, "/api/cron/editorial-link-check": { "get": { "operationId": "getCronEditorialLinkCheck", "summary": "PLA-4542 — scheduled detector for editorial `/products/*` link rot", "tags": [ "cron" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checked": { "type": "number" }, "checkedAt": { "type": "string" }, "emailDelivered": { "type": "boolean", "nullable": true }, "hubBrandFacets": { "type": "object", "properties": { "blockedFromRail": { "type": "number" }, "checked": { "type": "number" }, "deadLinks": { "type": "array", "items": { "type": "object", "properties": { "brandName": { "type": "string" }, "brandSlug": { "type": "string" }, "category": { "type": "string" }, "productCount": { "type": "number" }, "reason": { "type": "string", "enum": [ "deadLink", "suspectBrand" ] } }, "required": [ "brandName", "brandSlug", "category", "productCount", "reason" ] } }, "pass": { "type": "boolean" }, "shadowBrands": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "productCount": { "type": "number" }, "reason": { "type": "string", "enum": [ "invisibleMark", "nameCollision" ] }, "slug": { "type": "string" }, "twinSlug": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "name", "productCount", "reason", "slug", "twinSlug" ] } }, "suspectBrands": { "type": "array", "items": { "type": "object", "properties": { "brandName": { "type": "string" }, "brandSlug": { "type": "string" }, "category": { "type": "string" }, "productCount": { "type": "number" }, "reason": { "type": "string", "enum": [ "deadLink", "suspectBrand" ] } }, "required": [ "brandName", "brandSlug", "category", "productCount", "reason" ] } } }, "required": [ "blockedFromRail", "checked", "deadLinks", "pass", "shadowBrands", "suspectBrands" ], "nullable": true }, "miscategorized": { "type": "array", "items": { "type": "object", "properties": { "actualCategory": { "type": "string", "nullable": true }, "category": { "type": "string" }, "reason": { "type": "string", "enum": [ "missing", "miscategorized" ] }, "slug": { "type": "string" }, "source": { "type": "string" } }, "required": [ "category", "reason", "slug", "source" ] } }, "missing": { "type": "array", "items": { "type": "object", "properties": { "actualCategory": { "type": "string", "nullable": true }, "category": { "type": "string" }, "reason": { "type": "string", "enum": [ "missing", "miscategorized" ] }, "slug": { "type": "string" }, "source": { "type": "string" } }, "required": [ "category", "reason", "slug", "source" ] } }, "pass": { "type": "boolean" }, "status": { "type": "string" } }, "required": [ "checked", "checkedAt", "miscategorized", "missing", "pass", "status" ] }, "example": { "checked": 1, "checkedAt": "string", "emailDelivered": true, "hubBrandFacets": { "blockedFromRail": 1, "checked": 1, "deadLinks": [ { "brandName": "string", "brandSlug": "string", "category": "string", "productCount": 1, "reason": "deadLink" } ], "pass": true, "shadowBrands": [ { "name": "string", "productCount": 1, "reason": "invisibleMark", "slug": "string", "twinSlug": {} } ], "suspectBrands": [ { "brandName": "string", "brandSlug": "string", "category": "string", "productCount": 1, "reason": "deadLink" } ] }, "miscategorized": [ { "actualCategory": "string", "category": "string", "reason": "missing", "slug": "string", "source": "string" } ], "missing": [ { "actualCategory": "string", "category": "string", "reason": "missing", "slug": "string", "source": "string" } ], "pass": true, "status": "string" } } } } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Scheduled in vercel.json at \"0 9 * * *\" (daily). Why a cron and not a CI check: these slugs rot without a commit. `gigabyte-gaming-oc-rtx-4070-super` is still present in `src/data/seed/gpus.ts` and still 404s in production — no PR ever touched it, the catalog moved underneath it. A build-time gate cannot see that; only a scheduled resolution against the live catalog can. The complementary half runs in CI: the jest drift gate in `src/lib/seo/__tests__/editorial-product-links.test.ts` fails if a new hardcoded link enters the source tree without landing in the manifest this route reads, so nothing can be added unwatched. `?category=` narrows the sweep for ad-hoc probing.", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category slug.", "schema": { "type": "string" } } ] } }, "/api/cron/guide-price-drift": { "get": { "operationId": "getCronGuidePriceDrift", "summary": "PLA-4796 — scheduled detector for guide price drift", "tags": [ "cron" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkedAt": { "type": "string" }, "checkedGuides": { "type": "number" }, "checkedParts": { "type": "number" }, "dead": { "type": "array", "items": { "type": "object", "properties": { "detail": { "type": "string", "nullable": true }, "guide": { "type": "string" }, "product": { "type": "string" }, "reason": { "type": "string", "enum": [ "missing", "unpriced" ] }, "slug": { "type": "string" } }, "required": [ "guide", "product", "reason", "slug" ] } }, "guides": { "type": "array", "items": { "type": "object", "properties": { "cataloguePrice": { "type": "number" }, "driftPct": { "type": "number" }, "excluded": { "type": "number" }, "guide": { "type": "string" }, "quotedTotal": { "type": "number" } }, "required": [ "cataloguePrice", "driftPct", "excluded", "guide", "quotedTotal" ] } }, "parts": { "type": "array", "items": { "type": "object", "properties": { "catalogue": { "type": "number" }, "driftPct": { "type": "number" }, "guide": { "type": "string" }, "product": { "type": "string" }, "quoted": { "type": "number" }, "retailer": { "type": "string" }, "slug": { "type": "string" }, "source": { "type": "string", "enum": [ "retailer", "amazon" ] } }, "required": [ "catalogue", "driftPct", "guide", "product", "quoted", "retailer", "slug", "source" ] } }, "partTolerancePct": { "type": "number" }, "pass": { "type": "boolean" }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number" }, "basis": { "type": "number" }, "ratio": { "type": "number" }, "slug": { "type": "string" } }, "required": [ "amount", "basis", "ratio", "slug" ] } }, "status": { "type": "string" } }, "required": [ "checkedAt", "checkedGuides", "checkedParts", "dead", "guides", "partTolerancePct", "parts", "pass", "rejected", "status" ] }, "example": { "checkedAt": "string", "checkedGuides": 1, "checkedParts": 1, "dead": [ { "detail": "string", "guide": "string", "product": "string", "reason": "missing", "slug": "string" } ], "guides": [ { "cataloguePrice": 1, "driftPct": 1, "excluded": 1, "guide": "string", "quotedTotal": 1 } ], "parts": [ { "catalogue": 1, "driftPct": 1, "guide": "string", "product": "string", "quoted": 1, "retailer": "string", "slug": "string", "source": "retailer" } ], "partTolerancePct": 1, "pass": true, "rejected": [ { "amount": 1, "basis": 1, "ratio": 1, "slug": "string" } ], "status": "string" } } } } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Scheduled in vercel.json at \"30 9 * * *\" (daily, after editorial-link-check). WHY A CRON AND NOT A CI CHECK — the same argument PLA-4542 made for link rot, and this ticket is the proof it generalises. `guide-price-promise.test.ts` compares a guide's promise to its own `parts[].price`, so it is blind to the catalogue by construction: when prices move and the seed does not, the seed stays self-consistent and the suite stays green while every printed figure goes stale. Between the 2026-08-02 reconciliation and 2026-08-06 that is exactly what happened — 185 mismatched quotes, the worst a $609.99 line against a $1,389.00 catalogue price — with no failing test and no commit involved. `scripts/pla4568-verify-guide-prices.mts` is the deep version of this check and stays the repair tool: it also gates the printed totals, the live-price claims and the render layer. But it needs prod credentials, so it runs when a person runs it, and in those four days nobody did. This is the half that does not need a person. It reports rather than repairs. Re-pricing is an editorial pass — parts get swapped, promises get re-banded, prose gets rewritten — so the useful output is \"these figures are now wrong\", handed to whoever owns the copy. `?guide=` narrows the sweep for ad-hoc probing.", "parameters": [ { "name": "guide", "in": "query", "required": false, "description": "guide parameter.", "schema": { "type": "string" } } ] } }, "/api/cron/indexnow": { "get": { "operationId": "getCronIndexnow", "summary": "Daily IndexNow push for planmypc.com (PLA-2404)", "tags": [ "cron" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "deferred": { "type": "number" }, "failures": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "maxUrlsPerRun": { "type": "number" }, "ok": { "type": "boolean" }, "submittedFailed": { "type": "number" }, "submittedOk": { "type": "number" }, "urlCount": { "type": "number" }, "windowHours": { "type": "number" } }, "required": [ "deferred", "failures", "maxUrlsPerRun", "ok", "submittedFailed", "submittedOk", "urlCount", "windowHours" ] }, { "type": "object", "properties": { "deferred": { "type": "number" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "batch": { "type": "number" }, "batchSize": { "type": "number" }, "error": { "type": "string", "nullable": true }, "status": { "type": "number" }, "statusText": { "type": "string" }, "url": { "type": "string", "nullable": true } }, "required": [ "batch", "batchSize", "status", "statusText" ] } }, "maxUrlsPerRun": { "type": "number" }, "ok": { "type": "boolean" }, "submittedFailed": { "type": "number" }, "submittedOk": { "type": "number" }, "urlCount": { "type": "number" }, "windowHours": { "type": "number" } }, "required": [ "deferred", "failures", "maxUrlsPerRun", "ok", "submittedFailed", "submittedOk", "urlCount", "windowHours" ] } ] }, "example": { "deferred": 1, "failures": [ {} ], "maxUrlsPerRun": 1, "ok": true, "submittedFailed": 1, "submittedOk": 1, "urlCount": 1, "windowHours": 1 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "ok": { "type": "boolean" } }, "required": [ "error", "ok" ] }, "example": { "error": "string", "ok": true } } } } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Replaces the brittle macOS launchd job `com.planmypc.indexnow-daily`, which failed every run since 2026-06-12 because launchd lacked Full Disk Access to read the repo `.env`. Runs on the Pi's job timer (deploy/pi/jobs.conf). Submits DB rows updated in the last 48h (delta), one URL per request (PLA-2956), notifying Bing / Yandex / DuckDuckGo / etc. Requires INDEXNOW_KEY in env and the key file hosted at https://planmypc.com/{key}.txt. Bounded: at most INDEXNOW_MAX_URLS_PER_RUN URLs, taken from the front of `buildUrlsFromDb`'s priority order (editorial first, then products by most recent update), inside INDEXNOW_SUBMIT_BUDGET_MS. The rest is DEFERRED — logged with a count, not a failure — and stays a candidate for the next run, behind anything newer, while it is still inside the 48h window. Unbounded, the 2026-09-27 delta tried 10,695 URLs and ran 93 minutes; the job's curl had given up at 900 s." } }, "/api/cron/lenovo-price-sync": { "get": { "operationId": "getCronLenovoPriceSync", "summary": "PLA-1866 — demand-driven Lenovo price-sync sweep (PLA-1863 Step 5)", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auth: Authorization: Bearer $CRON_SECRET --- UNSCHEDULED as of PLA-4725 --- The route still works and can be invoked by hand; its `crons` entry (\"30 * /2 * * *\") is gone from vercel.json. In ~9 weeks of firing every two hours it produced exactly 6 ProductPrice rows, all on 2026-05-30, and it can never refresh them: the candidate query filters `prices: { none: { retailer: { slug: 'lenovo' } } }`, so a product leaves the candidate set permanently the moment it gets its first Lenovo price. Those 6 rows sat dark for 67 days and were shed by PLA-4725. Re-schedule only alongside a refresh path (the acquisition-only filter is the thing to fix). Lenovo publishes no Rakuten catalog feed, so the supply-driven sweep can't surface them — but Rakuten Product Search returns Lenovo's listings for a given product name. This cron is the Lenovo twin of the Newegg price-sync (PLA-1864): it sweeps Lenovo-branded products lacking a Lenovo ProductPrice, looks each up on Lenovo's merchant feed (mid 47364) via the shared `lookupRakutenProductMatch` primitive, and upserts a Lenovo ProductPrice when the fuzzy matcher confirms the candidate. --- Scope (PLA-2056) --- Unlike Newegg (a marketplace reselling the whole PC-parts catalog), Lenovo is a single-brand merchant. Its feed only carries Lenovo-branded gear, and the brand+model match guard can only clear when the catalog product's own brand is Lenovo. Sweeping the full 77.9k-product catalog therefore matched 0/250 every run (a 250-window held <1 Lenovo product). The sweep is scoped to manufacturer=LENOVO_MANUFACTURER_NAME so each chunk targets actually-eligible products — see lenovo-price-sync.ts for the full rationale. Query params (all optional): ?dryRun=1 — compute matches + report but write nothing ?limit=N — cap this run's chunk below the default (testing/probing) --- CEO design gate: provable < 300s completion (inherited from PLA-1864) --- Each invocation is bounded TWO ways so it can never approach the 300s Vercel function ceiling: 1. Chunk ceiling: at most LENOVO_PRICESYNC_CHUNK (250) products are fetched. 2. Wall-clock budget: the loop stops once elapsed time crosses LENOVO_PRICESYNC_WALL_CLOCK_BUDGET_MS (240s), leaving 60s of headroom for the final DB write + response serialization. The response reports `elapsedMs` + `avgLookupMs` so per-run latency is auditable for the PLA-1866 Step 4 acceptance check. --- URL contract --- `lookupRakutenProductMatch` returns the RAW merchant URL (not Rakuten's pre-wrapped ``); `buildAffiliateUrl` wraps it into a click.linksynergy.com deeplink at render. This is the same anti-double-wrap convention the rest of the codebase relies on (documented deviation from the PLA-1778 \"prefer linkurl\" note — see newegg-price-lookup.ts). --- Forward progress --- Progress is tracked by an IngestionState row keyed LENOVO_PRICESYNC_STATE_KEY (distinct from the Newegg sweep's row). We page by id cursor (`id > cursor`, ordered asc) so unmatched products are stepped past rather than re-fetched forever. When a chunk drains fully AND returns fewer than the ceiling, the pass is COMPLETE and the cursor resets to null so the next run starts fresh. Cron: every 2h offset 30m from the Newegg sweep (see vercel.json) so the two never run concurrently against the shared Rakuten ~100 req/min account cap." } }, "/api/cron/price-freshness-check": { "get": { "operationId": "getCronPriceFreshnessCheck", "summary": "Dead-man's-switch for the price refresh pipeline", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Checks whether the most recent asin_price_snapshots row is older than STALE_THRESHOLD_HOURS. If so, sends an alert email to the admin. Scheduled in vercel.json as a Vercel cron at \"0 0 * * *\" (daily, 00:00 UTC). Vercel cron invokes the path with GET, which this route exports. Auth is the shared CRON_SECRET bearer token (see verifyCronSecret); no other methods are exported." } }, "/api/cron/rakuten-price-sync": { "get": { "operationId": "getCronRakutenPriceSync", "summary": "PLA-1864 — demand-driven Newegg price-sync sweep", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Replaces the curated-seed overlay (PLA-1775) with a full Product-table sweep: find products that lack a Newegg ProductPrice, look each up on Rakuten's Product Search feed (mid=44583), and upsert a Newegg ProductPrice when the fuzzy matcher confirms the candidate is the same product. Query params (all optional): ?dryRun=1 — compute matches + report but write nothing ?limit=N — cap this run's chunk below the default (testing/probing) --- CEO design gate: provable < 300s completion --- Each invocation is bounded TWO ways so it can never approach the 300s Vercel function ceiling: 1. Chunk ceiling: at most NEWEGG_PRICESYNC_CHUNK (250) products are fetched. 2. Wall-clock budget: the loop stops once elapsed time crosses NEWEGG_PRICESYNC_WALL_CLOCK_BUDGET_MS (240s), leaving 60s of headroom for the final DB write + response serialization. At NEWEGG_PRICESYNC_REQUEST_SPACING_MS (650ms ≈ 92 req/min) pacing, 250 lookups take ~163s of pacing plus per-call latency; the 240s budget is the real guard if individual Rakuten calls run slow. The response reports `elapsedMs` + `avgLookupMs` so the measured latency can be audited per run. --- Forward progress --- Progress is tracked by an IngestionState row keyed NEWEGG_PRICESYNC_STATE_KEY (distinct from the retired supply-driven \"newegg\" row). We page by id cursor (`id > cursor`, ordered asc), so unmatched products — which stay in the \"no Newegg price\" set — are still stepped past rather than re-fetched forever. When a chunk drains fully AND returns fewer than the ceiling, the pass is COMPLETE and the cursor resets to null so the next run starts a fresh pass (picking up new products + retrying previously-unmatched ones). Cron: every 2h (see vercel.json). 12 runs/day × 250 ≈ 3,000 lookups/day." } }, "/api/cron/slow-query-check": { "get": { "operationId": "getCronSlowQueryCheck", "summary": "PLA-4390 — detector for the PLA-4383 class: an unindexed ORDER BY on the", "tags": [ "cron" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkedAt": { "type": "string" }, "emailDelivered": { "type": "boolean", "nullable": true }, "inventorySize": { "type": "number" }, "slowStatementError": { "type": "string", "nullable": true }, "slowStatements": { "type": "array", "items": { "type": "object", "properties": { "calls": { "type": "number" }, "mean_ms": { "type": "number" }, "query": { "type": "string" }, "queryid": { "type": "string", "nullable": true }, "total_s": { "type": "number" } }, "required": [ "calls", "mean_ms", "query", "queryid", "total_s" ] } }, "status": { "type": "string" }, "unindexedOrderedColumns": { "type": "array", "items": { "type": "object", "properties": { "callSites": { "type": "array", "items": { "type": "string" } }, "column": { "type": "string" }, "estRows": { "type": "number" }, "reach": { "type": "string", "enum": [ "render", "lib", "api" ] }, "table": { "type": "string" } }, "required": [ "callSites", "column", "estRows", "reach", "table" ] } } }, "required": [ "checkedAt", "inventorySize", "slowStatements", "status", "unindexedOrderedColumns" ] }, "example": { "checkedAt": "string", "emailDelivered": true, "inventorySize": 1, "slowStatementError": "string", "slowStatements": [ { "calls": 1, "mean_ms": 1, "query": "string", "queryid": "string", "total_s": 1 } ], "status": "string", "unindexedOrderedColumns": [ { "callSites": [ "string" ], "column": "string", "estRows": 1, "reach": "render", "table": "string" } ] } } } } }, "description": "render path. Auth: Authorization: Bearer $CRON_SECRET Scheduled in vercel.json at \"30 6 * * *\" (daily). Alerts by email when either signal fires. See `src/lib/db-health/slow-query-detector.ts` for why there are two. Why this exists: PLA-4383 took the whole affiliate surface dark and nothing alerted, because /api/health's DB probe is `SELECT 1` and stays fast while a single 1.6 s render-path query saturates the Supavisor client cap." } }, "/api/cron/snapshot-coverage": { "get": { "operationId": "getCronSnapshotCoverage", "summary": "Daily coverage monitor for the snapshot refresh pipeline", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Reports: - slugsRefreshedToday / totalAsinBearing (coverage %) - zero-snapshot products (ASINs that have never been captured) - stale >7 days count Designed to run daily (e.g. 23:00 UTC) via Vercel cron to give an end-of-day coverage snapshot. Logs metrics to console so they surface in Vercel Function logs." } }, "/api/cron/store-price-sync": { "get": { "operationId": "getCronStorePriceSync", "summary": "Store price pilot (docs/infra/store-price-pilot.md)", "tags": [ "cron" ], "responses": { "200": { "description": "OK" } }, "description": "Auth: Authorization: Bearer $CRON_SECRET Reads one pilot store (corsair, nzxt, keychron, glorious, central-computers) through its adapter and writes its prices as offers for the catalog products the reviewed mapping file binds (`runStoreSync`, the only writer of these retailers' rows). No affiliate program with any of them: the links are plain store URLs. Scheduled per store in deploy/pi/jobs.conf, so a store that blocks us fails alone. Kill switch: `STORE_PRICE_SYNC_DISABLED` = `*` or a comma list of slugs. A disabled store gets no request at all, and a real run deletes EVERY row of its retailer (a price we have stopped verifying must not stay up). A dry run of a disabled store only reports how many rows that would delete. Returns HTTP 500 — on the Pi nothing else alerts, and a failed systemd unit is the signal — when the run's status is - `blocked`: the store (or robots.txt) stopped the run; - `backoff`: a recent block's backoff is still running (24 h, or the store's Retry-After up to 7 days), so the store was not contacted. The unit keeps failing until the store is read again; - `failed`: the read failed without a block (pages requested but no mapped offer seen, or the adapter gave up on errors). `partial` (cut short by the request cap or the deadline) is a 200. Returns 409, with no store request and no write, while another run of the same store is in progress." } }, "/api/csp-report": { "post": { "operationId": "postCspReport", "summary": "Create csp report", "tags": [ "csp-report" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/csp-report`." } }, "/api/email/drip/open": { "get": { "operationId": "getEmailDripOpen", "summary": "List open", "tags": [ "email" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/email/drip/open`." } }, "/api/email/drip/unsubscribe": { "get": { "operationId": "getEmailDripUnsubscribe", "summary": "List unsubscribe", "tags": [ "email" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/email/drip/unsubscribe`." }, "post": { "operationId": "postEmailDripUnsubscribe", "summary": "Create unsubscribe", "tags": [ "email" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/email/drip/unsubscribe`." } }, "/api/errors": { "post": { "operationId": "postErrors", "summary": "Log a client-side error report", "tags": [ "errors" ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] }, "example": { "ok": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/errors`." } }, "/api/export": { "post": { "operationId": "postExport", "summary": "Export a build into a shareable format", "tags": [ "export" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ] }, "example": { "content": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/export`." } }, "/api/feeds/guides.xml": { "get": { "operationId": "getFeedsGuidesXml", "summary": "Get the guides RSS feed", "tags": [ "feeds" ], "responses": { "200": { "description": "OK", "content": { "application/rss+xml": { "schema": { "type": "string" }, "example": "string" } } }, "500": { "description": "Internal server error", "content": { "application/xml": { "schema": { "type": "string" }, "example": "string" } } } }, "description": "Auto-generated from the route handler for `/api/feeds/guides.xml`." } }, "/api/feeds/prices.xml": { "get": { "operationId": "getFeedsPricesXml", "summary": "Get the price feed RSS feed", "tags": [ "feeds" ], "responses": { "200": { "description": "OK", "content": { "application/rss+xml": { "schema": { "type": "string" }, "example": "string" } } }, "500": { "description": "Internal server error", "content": { "application/xml": { "schema": { "type": "string" }, "example": "string" } } } }, "description": "Auto-generated from the route handler for `/api/feeds/prices.xml`." } }, "/api/forums": { "get": { "operationId": "getForums", "summary": "List forum categories", "tags": [ "forums" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "memberCount": { "type": "number" } }, "required": [ "categories", "memberCount" ] }, "example": { "categories": [ {} ], "memberCount": 1 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/forums`." } }, "/api/forums/{category}": { "get": { "operationId": "getForumsCategory", "summary": "Get a forum category with topics", "tags": [ "forums" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "object", "additionalProperties": true }, "limit": { "type": "number" }, "page": { "type": "number" }, "topics": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total": { "type": "number" } }, "required": [ "category", "limit", "page", "topics", "total" ] }, "example": { "category": {}, "limit": 1, "page": 1, "topics": [ {} ], "total": 1 } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/forums/{category}`.", "parameters": [ { "name": "category", "in": "path", "required": true, "description": "Category slug.", "schema": { "type": "string" } } ] }, "post": { "operationId": "postForumsCategory", "summary": "Create a topic in a forum category", "tags": [ "forums" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "avatarUrl": { "type": "string", "nullable": true }, "body": { "type": "string" }, "categoryName": { "type": "string" }, "categorySlug": { "type": "string" }, "createdAt": { "type": "string" }, "existing": { "type": "boolean" }, "id": { "type": "string" }, "lastReplyAt": { "type": "string" }, "locked": { "type": "boolean" }, "pinned": { "type": "boolean" }, "replyCount": { "type": "number" }, "slug": { "type": "string" }, "title": { "type": "string" }, "userId": { "type": "string" }, "username": { "type": "string" }, "viewCount": { "type": "number" } }, "required": [ "avatarUrl", "body", "categoryName", "categorySlug", "createdAt", "existing", "id", "lastReplyAt", "locked", "pinned", "replyCount", "slug", "title", "userId", "username", "viewCount" ] }, "example": { "avatarUrl": "string", "body": "string", "categoryName": "string", "categorySlug": "string", "createdAt": "string", "existing": true, "id": "string", "lastReplyAt": "string", "locked": true, "pinned": true, "replyCount": 1, "slug": "string", "title": "string", "userId": "string", "username": "string", "viewCount": 1 } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "avatarUrl": { "type": "string", "nullable": true }, "body": { "type": "string" }, "categoryName": { "type": "string" }, "categorySlug": { "type": "string" }, "createdAt": { "type": "string" }, "existing": { "type": "boolean" }, "id": { "type": "string" }, "lastReplyAt": { "type": "string" }, "locked": { "type": "boolean" }, "pinned": { "type": "boolean" }, "replyCount": { "type": "number" }, "slug": { "type": "string" }, "title": { "type": "string" }, "userId": { "type": "string" }, "username": { "type": "string" }, "viewCount": { "type": "number" } }, "required": [ "avatarUrl", "body", "categoryName", "categorySlug", "createdAt", "existing", "id", "lastReplyAt", "locked", "pinned", "replyCount", "slug", "title", "userId", "username", "viewCount" ] }, "example": { "avatarUrl": "string", "body": "string", "categoryName": "string", "categorySlug": "string", "createdAt": "string", "existing": true, "id": "string", "lastReplyAt": "string", "locked": true, "pinned": true, "replyCount": 1, "slug": "string", "title": "string", "userId": "string", "username": "string", "viewCount": 1 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/forums/{category}`.", "parameters": [ { "name": "category", "in": "path", "required": true, "description": "Category slug.", "schema": { "type": "string" } } ], "security": [ { "supabaseSession": [] } ] } }, "/api/forums/{category}/{topic}": { "get": { "operationId": "getForumsCategoryTopic", "summary": "Get a forum topic", "tags": [ "forums" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorReputation": { "type": "object", "properties": { "activity": { "type": "object", "properties": { "buildCommentsReceived": { "type": "number" }, "buildLikesReceived": { "type": "number" }, "buildsPublished": { "type": "number" }, "forumPosts": { "type": "number" }, "forumReplies": { "type": "number" }, "reviews": { "type": "number" } }, "required": [ "buildCommentsReceived", "buildLikesReceived", "buildsPublished", "forumPosts", "forumReplies", "reviews" ] }, "description": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "number" }, "tier": { "type": "string", "enum": [ "newcomer", "contributor", "regular", "trusted", "legend" ] } }, "required": [ "activity", "description", "label", "score", "tier" ] }, "avatarUrl": { "type": "string", "nullable": true }, "body": { "type": "string" }, "categorySlug": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "lastReplyAt": { "type": "string" }, "linkedBuild": { "type": "object", "additionalProperties": true, "nullable": true }, "locked": { "type": "boolean" }, "pinned": { "type": "boolean" }, "replies": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "replyCount": { "type": "number" }, "slug": { "type": "string" }, "title": { "type": "string" }, "userId": { "type": "string" }, "username": { "type": "string" }, "viewCount": { "type": "number" } }, "required": [ "authorReputation", "avatarUrl", "body", "categorySlug", "createdAt", "id", "lastReplyAt", "linkedBuild", "locked", "pinned", "replies", "replyCount", "slug", "title", "userId", "username", "viewCount" ] }, "example": { "authorReputation": { "activity": { "buildCommentsReceived": 1, "buildLikesReceived": 1, "buildsPublished": 1, "forumPosts": 1, "forumReplies": 1, "reviews": 1 }, "description": "string", "label": "string", "score": 1, "tier": "newcomer" }, "avatarUrl": "string", "body": "string", "categorySlug": "string", "createdAt": "string", "id": "string", "lastReplyAt": "string", "linkedBuild": {}, "locked": true, "pinned": true, "replies": [ {} ], "replyCount": 1, "slug": "string", "title": "string", "userId": "string", "username": "string", "viewCount": 1 } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/forums/{category}/{topic}`.", "parameters": [ { "name": "category", "in": "path", "required": true, "description": "Category slug.", "schema": { "type": "string" } }, { "name": "topic", "in": "path", "required": true, "description": "Topic slug.", "schema": { "type": "string" } } ] }, "post": { "operationId": "postForumsCategoryTopic", "summary": "Reply to a forum topic", "tags": [ "forums" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "avatarUrl": { "type": "string", "nullable": true }, "body": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "userId": { "type": "string" }, "username": { "type": "string" } }, "required": [ "avatarUrl", "body", "createdAt", "id", "userId", "username" ] }, "example": { "avatarUrl": "string", "body": "string", "createdAt": "string", "id": "string", "userId": "string", "username": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/forums/{category}/{topic}`.", "parameters": [ { "name": "category", "in": "path", "required": true, "description": "Category slug.", "schema": { "type": "string" } }, { "name": "topic", "in": "path", "required": true, "description": "Topic slug.", "schema": { "type": "string" } } ], "security": [ { "supabaseSession": [] } ] } }, "/api/forums/{category}/{topic}/replies/{replyId}": { "delete": { "operationId": "deleteForumsCategoryTopicRepliesReplyId", "summary": "Delete replies", "tags": [ "forums" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "example": { "deleted": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/forums/{category}/{topic}/replies/{replyId}`.", "parameters": [ { "name": "category", "in": "path", "required": true, "description": "Category slug.", "schema": { "type": "string" } }, { "name": "topic", "in": "path", "required": true, "description": "Topic slug.", "schema": { "type": "string" } }, { "name": "replyId", "in": "path", "required": true, "description": "replyId parameter.", "schema": { "type": "string" } } ], "security": [ { "supabaseSession": [] } ] } }, "/api/game-fps": { "get": { "operationId": "getGameFps", "summary": "List supported game FPS presets", "tags": [ "game-fps" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "cpu": { "type": "string" }, "cpuCategorySlug": { "type": "string", "nullable": true }, "cpuSlug": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "fps": { "type": "number" }, "game": { "type": "string" }, "gpu": { "type": "string" }, "gpuCategorySlug": { "type": "string", "nullable": true }, "gpuSlug": { "type": "string", "nullable": true }, "id": { "type": "string" }, "ram": { "type": "string" }, "resolution": { "type": "string" }, "settings": { "type": "string" }, "source": { "type": "string" }, "upvotes": { "type": "number" }, "username": { "type": "string" } }, "required": [ "cpu", "cpuCategorySlug", "cpuSlug", "createdAt", "fps", "game", "gpu", "gpuCategorySlug", "gpuSlug", "id", "ram", "resolution", "settings", "source", "upvotes", "username" ] } }, "limit": { "type": "number" }, "page": { "type": "number" }, "total": { "type": "number" } }, "required": [ "entries", "limit", "page", "total" ] }, "example": { "entries": [ { "cpu": "string", "cpuCategorySlug": "string", "cpuSlug": "string", "createdAt": "2026-04-10T12:00:00.000Z", "fps": 1, "game": "string", "gpu": "string", "gpuCategorySlug": "string", "gpuSlug": "string", "id": "string", "ram": "string", "resolution": "string", "settings": "string", "source": "string", "upvotes": 1, "username": "string" } ], "limit": 1, "page": 1, "total": 1 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/game-fps`. Query params: `cpu`, `game`, `gpu`, `q`.", "parameters": [ { "name": "cpu", "in": "query", "required": false, "description": "cpu parameter.", "schema": { "type": "string" } }, { "name": "game", "in": "query", "required": false, "description": "game parameter.", "schema": { "type": "string" } }, { "name": "gpu", "in": "query", "required": false, "description": "gpu parameter.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search query.", "schema": { "type": "string" } } ] }, "post": { "operationId": "postGameFps", "summary": "Estimate FPS for a game build", "tags": [ "game-fps" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "cpu": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "fps": { "type": "number" }, "game": { "type": "string" }, "gpu": { "type": "string" }, "id": { "type": "string" }, "ram": { "type": "string" }, "resolution": { "type": "string" }, "settings": { "type": "string" }, "source": { "type": "string" }, "upvotes": { "type": "number" }, "username": { "type": "string" } }, "required": [ "cpu", "createdAt", "fps", "game", "gpu", "id", "ram", "resolution", "settings", "source", "upvotes", "username" ] }, "example": { "cpu": "string", "createdAt": "2026-04-10T12:00:00.000Z", "fps": 1, "game": "string", "gpu": "string", "id": "string", "ram": "string", "resolution": "string", "settings": "string", "source": "string", "upvotes": 1, "username": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/game-fps`.", "security": [ { "supabaseSession": [] } ] } }, "/api/guides": { "get": { "operationId": "getGuides", "summary": "List published guides", "tags": [ "guides" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "guides": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "limit": { "type": "number" }, "page": { "type": "number" }, "total": { "type": "number" } }, "required": [ "guides", "limit", "page", "total" ] }, "example": { "guides": [ {} ], "limit": 1, "page": 1, "total": 1 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/guides`." } }, "/api/guides/{slug}": { "get": { "operationId": "getGuidesSlug", "summary": "Get a guide by slug", "tags": [ "guides" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "budget": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "guideParts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "id": { "type": "string" }, "imageUrl": { "type": "string", "nullable": true }, "published": { "type": "boolean" }, "slug": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "type": "string" }, "useCase": { "type": "string" } }, "required": [ "body", "budget", "createdAt", "description", "guideParts", "id", "imageUrl", "published", "slug", "title", "updatedAt", "useCase" ] }, "example": { "body": "string", "budget": "string", "createdAt": "string", "description": "string", "guideParts": [ {} ], "id": "string", "imageUrl": "string", "published": true, "slug": "string", "title": "string", "updatedAt": "string", "useCase": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/guides/{slug}`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/health": { "get": { "operationId": "getHealth", "summary": "Get application health status", "tags": [ "health" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checks": { "type": "object", "additionalProperties": { "type": "object", "properties": { "detail": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "error", "ok", "warn" ] } }, "required": [ "status" ] } }, "status": { "type": "string", "enum": [ "error", "ok", "degraded" ] }, "timestamp": { "type": "string" } }, "required": [ "checks", "status", "timestamp" ] }, "example": { "checks": {}, "status": "error", "timestamp": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/health`." } }, "/api/internal/deploy-staleness": { "get": { "operationId": "getInternalDeployStaleness", "summary": "PLA-1804, carved from PLA-1176 AC#5", "tags": [ "internal" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ageHours": { "type": "number" }, "deploymentId": { "type": "string", "nullable": true }, "isStale": { "type": "boolean" }, "latestReadyAt": { "type": "string", "nullable": true }, "source": { "type": "string" }, "status": { "type": "string" }, "thresholdHours": { "type": "number" } }, "required": [ "ageHours", "deploymentId", "isStale", "latestReadyAt", "source", "status", "thresholdHours" ] }, "example": { "ageHours": 1, "deploymentId": "string", "isStale": true, "latestReadyAt": "string", "source": "string", "status": "string", "thresholdHours": 1 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "502": { "description": "HTTP 502", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "status": { "type": "string" } }, "required": [ "error", "status" ] }, "example": { "error": "string", "status": "string" } } } } }, "description": "Dead-man's-switch for production deploy promotion. Queries the Vercel Deployments API for the latest `state=READY` production deploy and alerts (Sentry) when its age exceeds DEPLOY_STALENESS_THRESHOLD_HOURS (6h). Auth: Authorization: Bearer $CRON_SECRET (see verifyCronSecret). Scheduled hourly via the `crons` entry in vercel.json. Vercel cron sends GET, which this route exports. Verification hook (AC#3): an authenticated caller may pass `?forceStaleTimestamp=` to inject a fake \"latest READY deploy\" timestamp and exercise the alert path end-to-end without waiting for a real halt. This is only reachable behind the CRON_SECRET gate.", "parameters": [ { "name": "forceStaleTimestamp", "in": "query", "required": false, "description": "forceStaleTimestamp parameter.", "schema": { "type": "string" } } ] } }, "/api/internal/referrer-events": { "post": { "operationId": "postInternalReferrerEvents", "summary": "Create referrer events", "tags": [ "internal" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] }, "example": { "ok": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/internal/referrer-events`." } }, "/api/internal/revalidate": { "post": { "operationId": "postInternalRevalidate", "summary": "PLA-2818 (slice A of PLA-2814)", "tags": [ "internal" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string" } }, "requestedCategories": { "type": "number" }, "requestedPaths": { "type": "number" }, "requestedSlugs": { "type": "number" }, "revalidatedBrands": { "type": "number" }, "revalidatedBrowse": { "type": "number" }, "revalidatedPaths": { "type": "number" }, "status": { "type": "string" } }, "required": [ "paths", "requestedCategories", "requestedPaths", "requestedSlugs", "revalidatedBrands", "revalidatedBrowse", "revalidatedPaths", "status" ] }, "example": { "paths": [ "string" ], "requestedCategories": 1, "requestedPaths": 1, "requestedSlugs": 1, "revalidatedBrands": 1, "revalidatedBrowse": 1, "revalidatedPaths": 1, "status": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "fieldErrors": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" }, "nullable": true }, "paths": { "type": "array", "items": { "type": "string" }, "nullable": true }, "slugs": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "formErrors": { "type": "array", "items": { "type": "string" } } }, "required": [ "fieldErrors", "formErrors" ] }, "error": { "type": "string" } }, "required": [ "details", "error" ] } ] }, "example": { "error": "string" } } } }, "413": { "description": "HTTP 413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Change-driven ISR revalidation bridge for out-of-process price pipelines that can't call `revalidatePath()` in-process. The Rakuten price-sync route revalidates directly; this HTTP endpoint is the entry point for everything else — notably the Amazon/ASIN snapshot refresh that runs DB-side via pg_cron (PLA-1793 round-robin), which has no Next.js request context. Auth: `Authorization: Bearer $CRON_SECRET` (the single shared cron secret, via {@link verifyCronSecret}). Unauthenticated requests get 401. Body: `{ \"slugs\": string[], \"categories\": string[], \"paths\": string[] }` - `slugs` — Product.slug values whose price/data changed. The category segment of each PDP path (`/products//`) is resolved from the DB, so callers only need the slug. Each touched product's category listing is revalidated too. - `categories` — category URL slugs (e.g. \"video-card\") to revalidate the `/products/` listing directly. - `paths` — literal site-relative paths, for the pages a slug CANNOT name (PLA-4900). Deriving the PDP path from the slug reads the row's CURRENT category, so when a product's category is corrected, its page under the OLD category is unreachable from every input above — while still being an indexed, ISR-cached 200 that now duplicates the survivor for up to the 30-day window. Same shape as the PLA-4798 retired-slug hole one level up: there the row was gone, here the path is. Cost note: byte-identical revalidation costs ZERO Vercel ISR write units — writes bill only when regenerated output actually differs ($4/1M units, 1 unit = 8KB). Over-calling is therefore cheap and safe. Security checklist (PLA-1410/1411 pattern): - Zod schema on body ✓ - payload-size cap (100KB) ✓ - Authn: CRON_SECRET bearer ✓ - Authz/IDOR: N/A — no per-user resource; caller is trusted infra holding the shared cron secret, and revalidation only regenerates PUBLIC pages that already return the same 200 content to everyone. - Rate limit: N/A — secret-gated internal endpoint; work is hard-bounded by MAX_SLUGS/MAX_CATEGORIES/MAX_PATHS so a call can't fan out unboundedly. `paths` widens WHICH pages a holder of the secret can regenerate, not what it can read or write: `revalidatePath` only ever re-renders a public page from the same DB every visitor already sees, and the schema refuses anything that isn't a site-relative pathname." } }, "/api/internal/web-vitals-report": { "get": { "operationId": "getInternalWebVitalsReport", "summary": "CRON_SECRET-authenticated, repeatable field-quality gate report. The fixed", "tags": [ "internal" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "routeFamilies": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "thresholds": { "type": "object", "additionalProperties": true }, "window": { "type": "object", "additionalProperties": true } }, "required": [ "routeFamilies", "thresholds", "window" ] }, "example": { "routeFamilies": [ {} ], "thresholds": {}, "window": {} } } } } }, "description": "28-day window and 30-sample minimum are returned with every response." } }, "/api/news": { "get": { "operationId": "getNews", "summary": "List published news articles", "tags": [ "news" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "articles": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "articles" ] }, "example": { "articles": [ {} ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/news`." } }, "/api/news/{slug}": { "get": { "operationId": "getNewsSlug", "summary": "Get a news article by slug", "tags": [ "news" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "author": { "type": "string" }, "body": { "type": "string" }, "category": { "type": "string" }, "excerpt": { "type": "string" }, "featured": { "type": "boolean" }, "id": { "type": "string" }, "imageUrl": { "type": "string", "nullable": true }, "publishedAt": { "type": "string" }, "readTime": { "type": "number" }, "slug": { "type": "string" }, "title": { "type": "string" } }, "required": [ "author", "body", "category", "excerpt", "featured", "id", "imageUrl", "publishedAt", "readTime", "slug", "title" ] }, "example": { "author": "string", "body": "string", "category": "string", "excerpt": "string", "featured": true, "id": "string", "imageUrl": "string", "publishedAt": "string", "readTime": 1, "slug": "string", "title": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/news/{slug}`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/newsletter": { "post": { "operationId": "postNewsletter", "summary": "Create a newsletter subscription", "tags": [ "newsletter" ], "responses": { "200": { "description": "OK" } }, "description": "Auto-generated from the route handler for `/api/newsletter`." }, "get": { "operationId": "getNewsletter", "summary": "Get newsletter subscription statistics", "tags": [ "newsletter" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number" } }, "required": [ "count" ] }, "example": { "count": 1 } } } } }, "description": "Auto-generated from the route handler for `/api/newsletter`." } }, "/api/newsletter/unsubscribe": { "get": { "operationId": "getNewsletterUnsubscribe", "summary": "Unsubscribe from the newsletter", "tags": [ "newsletter" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/newsletter/unsubscribe`. Query params: `token`.", "parameters": [ { "name": "token", "in": "query", "required": true, "description": "Verification token.", "schema": { "type": "string" } } ] } }, "/api/notifications": { "get": { "operationId": "getNotifications", "summary": "List notifications for the current user", "tags": [ "notifications" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "unreadCount": { "type": "number" } }, "required": [ "notifications", "unreadCount" ] }, { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "properties": { "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "link": { "type": "string", "nullable": true }, "read": { "type": "boolean" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "PRICE_DROP", "BACK_IN_STOCK", "BUILD_COMMENT", "REVIEW_REPLY", "FORUM_REPLY", "SYSTEM" ] }, "userId": { "type": "string" } }, "required": [ "body", "createdAt", "id", "link", "read", "title", "type", "userId" ] } }, "unreadCount": { "type": "number" } }, "required": [ "notifications", "unreadCount" ] } ] }, "example": { "notifications": [ {} ], "unreadCount": 1 } } } } }, "description": "Auto-generated from the route handler for `/api/notifications`.", "security": [ { "supabaseSession": [] } ] }, "post": { "operationId": "postNotifications", "summary": "Create a notification", "tags": [ "notifications" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "link": { "type": "string", "nullable": true }, "read": { "type": "boolean" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "PRICE_DROP", "BACK_IN_STOCK", "BUILD_COMMENT", "REVIEW_REPLY", "FORUM_REPLY", "SYSTEM" ] }, "userId": { "type": "string" } }, "required": [ "body", "createdAt", "id", "link", "read", "title", "type", "userId" ] }, "example": { "body": "string", "createdAt": "2026-04-10T12:00:00.000Z", "id": "string", "link": "string", "read": true, "title": "string", "type": "PRICE_DROP", "userId": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Requires either: 1. CRON_SECRET Bearer token (for cron jobs / internal services), or 2. An authenticated admin session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bodyText": { "type": "string" }, "link": { "type": "string", "nullable": true }, "title": { "type": "string" }, "type": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "title", "type", "userId" ] }, "example": { "bodyText": "string", "link": "string", "title": "string", "type": "string", "userId": "string" } } } }, "security": [ { "supabaseSession": [] } ] }, "patch": { "operationId": "patchNotifications", "summary": "Mark notifications as read", "tags": [ "notifications" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "details": { "type": "object", "properties": { "fieldErrors": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "nullable": true }, "markAllRead": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "formErrors": { "type": "array", "items": { "type": "string" } } }, "required": [ "fieldErrors", "formErrors" ] }, "error": { "type": "string" } }, "required": [ "details", "error" ] }, "example": { "details": { "fieldErrors": { "ids": [ "string" ], "markAllRead": [ "string" ] }, "formErrors": [ "string" ] }, "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/notifications`.", "security": [ { "supabaseSession": [] } ] } }, "/api/parametric/preview": { "post": { "operationId": "postParametricPreview", "summary": "Create preview", "tags": [ "parametric" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "candidateCeilingExceeded": { "type": "boolean" }, "counts": { "type": "object", "properties": { "candidates": { "type": "number" }, "eligible": { "type": "number" }, "excluded": { "type": "number" } }, "required": [ "candidates", "eligible", "excluded" ] }, "excluded": { "type": "array", "items": { "type": "object", "properties": { "copy": { "type": "object", "properties": { "detail": { "type": "string" }, "label": { "type": "string" }, "tone": { "type": "string", "enum": [ "warning", "info", "excluded", "neutral" ] } }, "required": [ "detail", "label", "tone" ] }, "count": { "type": "number" }, "reason": { "type": "string", "enum": [ "discontinued", "not_in_catalog", "category_mismatch", "facet_unmatched", "price_below_min", "price_above_max", "price_unavailable", "region_unavailable", "merchant_denied", "merchant_not_allowed", "stock_out", "compat_issue", "compat_not_verifiable", "explicitly_excluded" ] }, "sample": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "object", "additionalProperties": true, "nullable": true }, "productSlug": { "type": "string" } }, "required": [ "name", "productSlug" ] } } }, "required": [ "copy", "count", "reason", "sample" ] } }, "fallbacks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "offer": { "type": "object", "properties": { "detail": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "offer_current", "offer_stale", "offer_unknown" ] }, "tone": { "type": "string", "enum": [ "warning", "info", "excluded", "neutral" ] } }, "required": [ "detail", "label", "state", "tone" ] }, "priceCents": { "type": "number", "nullable": true }, "productId": { "type": "string" }, "productSlug": { "type": "string" } }, "required": [ "name", "offer", "priceCents", "productId", "productSlug" ] } }, "outcome": { "type": "object", "properties": { "detail": { "type": "string" }, "label": { "type": "string" }, "tone": { "type": "string", "enum": [ "warning", "info", "excluded", "neutral" ] } }, "required": [ "detail", "label", "tone" ] }, "resolution": { "type": "object", "properties": { "criteriaSchemaVersion": { "type": "number", "enum": [ 1 ] }, "dataFreshness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fresh", "stale", "unavailable" ] }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "status", "updatedAt" ] }, "evaluatedAt": { "type": "string" }, "excluded": { "type": "array", "items": { "type": "object", "properties": { "facetKey": { "type": "string", "nullable": true }, "productId": { "type": "string" }, "productSlug": { "type": "string" }, "reason": { "type": "string", "enum": [ "discontinued", "not_in_catalog", "category_mismatch", "facet_unmatched", "price_below_min", "price_above_max", "price_unavailable", "region_unavailable", "merchant_denied", "merchant_not_allowed", "stock_out", "compat_issue", "compat_not_verifiable", "explicitly_excluded" ] } }, "required": [ "productId", "productSlug", "reason" ] } }, "fallbacks": { "type": "array", "items": { "type": "object", "properties": { "compatRank": { "type": "number", "enum": [ 0, 2, 1 ] }, "facetKey": { "type": "string", "nullable": true }, "offerState": { "type": "string", "enum": [ "offer_current", "offer_stale", "offer_unknown" ] }, "priceCents": { "type": "number", "nullable": true }, "productId": { "type": "string" }, "productSlug": { "type": "string" }, "reason": { "type": "string", "enum": [ "discontinued", "not_in_catalog", "category_mismatch", "facet_unmatched", "price_below_min", "price_above_max", "price_unavailable", "region_unavailable", "merchant_denied", "merchant_not_allowed", "stock_out", "compat_issue", "compat_not_verifiable", "explicitly_excluded" ] } }, "required": [ "compatRank", "offerState", "priceCents", "productId", "productSlug", "reason" ] } }, "outcome": { "type": "string", "enum": [ "locked", "resolved", "preserved", "unresolved" ] }, "priceKey": { "type": "string", "enum": [ "bestOfferPrice", "retailerOfferPrice" ] }, "ruleVersion": { "type": "number", "enum": [ 1 ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "no_match", "stale_data_hold", "previous_winner_ineligible", "winner_changed", "criteria_invalid" ] }, "validation": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true } }, "required": [ "code" ] } }, "winner": { "type": "object", "properties": { "compatRank": { "type": "number", "enum": [ 0, 2, 1 ] }, "offerState": { "type": "string", "enum": [ "offer_current", "offer_stale", "offer_unknown" ] }, "priceCents": { "type": "number", "nullable": true }, "productId": { "type": "string" }, "productSlug": { "type": "string" } }, "required": [ "compatRank", "offerState", "priceCents", "productId", "productSlug" ], "nullable": true } }, "required": [ "criteriaSchemaVersion", "dataFreshness", "evaluatedAt", "excluded", "fallbacks", "outcome", "priceKey", "ruleVersion", "warnings", "winner" ] }, "runnerUp": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "offer": { "type": "object", "properties": { "detail": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "offer_current", "offer_stale", "offer_unknown" ] }, "tone": { "type": "string", "enum": [ "warning", "info", "excluded", "neutral" ] } }, "required": [ "detail", "label", "state", "tone" ] }, "priceCents": { "type": "number", "nullable": true }, "productId": { "type": "string" }, "productSlug": { "type": "string" } }, "required": [ "name", "offer", "priceCents", "productId", "productSlug" ], "nullable": true }, "validation": { "type": "array", "items": { "type": "object", "properties": { "detail": { "type": "string" }, "label": { "type": "string" }, "tone": { "type": "string", "enum": [ "warning", "info", "excluded", "neutral" ] } }, "required": [ "detail", "label", "tone" ] } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "detail": { "type": "string" }, "label": { "type": "string" }, "tone": { "type": "string", "enum": [ "warning", "info", "excluded", "neutral" ] } }, "required": [ "detail", "label", "tone" ] } }, "whyItWon": { "type": "object", "properties": { "detail": { "type": "string" }, "id": { "type": "string", "enum": [ "price", "compatibility", "sole_candidate", "offer_state", "catalog_key" ] }, "label": { "type": "string" }, "step": { "type": "number", "nullable": true } }, "required": [ "detail", "id", "label", "step" ], "nullable": true }, "winner": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "offer": { "type": "object", "properties": { "detail": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "offer_current", "offer_stale", "offer_unknown" ] }, "tone": { "type": "string", "enum": [ "warning", "info", "excluded", "neutral" ] } }, "required": [ "detail", "label", "state", "tone" ] }, "priceCents": { "type": "number", "nullable": true }, "productId": { "type": "string" }, "productSlug": { "type": "string" } }, "required": [ "name", "offer", "priceCents", "productId", "productSlug" ], "nullable": true } }, "required": [ "candidateCeilingExceeded", "counts", "excluded", "fallbacks", "outcome", "resolution", "runnerUp", "validation", "warnings", "whyItWon", "winner" ] }, { "type": "object", "additionalProperties": true } ] }, "example": { "candidateCeilingExceeded": true, "counts": { "candidates": 1, "eligible": 1, "excluded": 1 }, "excluded": [ { "copy": { "detail": "string", "label": "string", "tone": "warning" }, "count": 1, "reason": "discontinued", "sample": [ { "name": {}, "productSlug": "string" } ] } ], "fallbacks": [ { "name": "string", "offer": { "detail": "string", "label": "string", "state": "offer_current", "tone": "warning" }, "priceCents": 1, "productId": "string", "productSlug": "string" } ], "outcome": { "detail": "string", "label": "string", "tone": "warning" }, "resolution": { "criteriaSchemaVersion": 1, "dataFreshness": { "status": "fresh", "updatedAt": "string" }, "evaluatedAt": "string", "excluded": [ { "facetKey": "string", "productId": "string", "productSlug": "string", "reason": "discontinued" } ], "fallbacks": [ { "compatRank": 0, "facetKey": "string", "offerState": "offer_current", "priceCents": 1, "productId": "string", "productSlug": "string", "reason": "discontinued" } ], "outcome": "locked", "priceKey": "bestOfferPrice", "ruleVersion": 1, "warnings": [ { "code": "no_match", "validation": [ {} ] } ], "winner": { "compatRank": 0, "offerState": "offer_current", "priceCents": 1, "productId": "string", "productSlug": "string" } }, "runnerUp": { "name": "string", "offer": { "detail": "string", "label": "string", "state": "offer_current", "tone": "warning" }, "priceCents": 1, "productId": "string", "productSlug": "string" }, "validation": [ { "detail": "string", "label": "string", "tone": "warning" } ], "warnings": [ { "detail": "string", "label": "string", "tone": "warning" } ], "whyItWon": { "detail": "string", "id": "price", "label": "string", "step": 1 }, "winner": { "name": "string", "offer": { "detail": "string", "label": "string", "state": "offer_current", "tone": "warning" }, "priceCents": 1, "productId": "string", "productSlug": "string" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "error", "issues" ] } ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/parametric/preview`." } }, "/api/price-alerts/check": { "post": { "operationId": "postPriceAlertsCheck", "summary": "Run the scheduled price alert check", "tags": [ "price-alerts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checked": { "type": "number" }, "emailsSent": { "type": "number" }, "message": { "type": "string" }, "triggered": { "type": "number" } }, "required": [ "checked", "emailsSent", "message", "triggered" ] }, "example": { "checked": 1, "emailsSent": 1, "message": "string", "triggered": 1 } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Thin wrapper around checkPriceAlerts() for manual/cron trigger. Auth: Authorization: Bearer $CRON_SECRET" } }, "/api/prices": { "get": { "operationId": "getPrices", "summary": "List current product prices", "tags": [ "prices" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "current": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "history": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "current", "history" ] }, "example": { "current": [ {} ], "history": [ {} ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/prices`. Query params: `slug`.", "parameters": [ { "name": "slug", "in": "query", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/prices/trends": { "get": { "operationId": "getPricesTrends", "summary": "Get product price trends", "tags": [ "prices" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "trend": { "type": "object", "properties": { "averagePrice": { "type": "number", "nullable": true }, "currentPrice": { "type": "number", "nullable": true }, "direction": { "type": "string", "enum": [ "up", "down", "stable" ] }, "highestPrice": { "type": "number", "nullable": true }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "price": { "type": "number" } }, "required": [ "date", "price" ] } }, "lowestPrice": { "type": "number", "nullable": true }, "priceChange30d": { "type": "number", "nullable": true }, "priceChangePct30d": { "type": "number", "nullable": true }, "slug": { "type": "string" } }, "required": [ "averagePrice", "currentPrice", "direction", "highestPrice", "history", "lowestPrice", "priceChange30d", "priceChangePct30d", "slug" ] } }, "required": [ "trend" ] }, { "type": "object", "properties": { "biggestDrops": { "type": "array", "items": { "type": "object", "properties": { "averagePrice": { "type": "number", "nullable": true }, "currentPrice": { "type": "number", "nullable": true }, "direction": { "type": "string", "enum": [ "up", "down", "stable" ] }, "highestPrice": { "type": "number", "nullable": true }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "price": { "type": "number" } }, "required": [ "date", "price" ] } }, "lowestPrice": { "type": "number", "nullable": true }, "priceChange30d": { "type": "number", "nullable": true }, "priceChangePct30d": { "type": "number", "nullable": true }, "slug": { "type": "string" } }, "required": [ "averagePrice", "currentPrice", "direction", "highestPrice", "history", "lowestPrice", "priceChange30d", "priceChangePct30d", "slug" ] } } }, "required": [ "biggestDrops" ] }, { "type": "object", "properties": { "stats": { "type": "object", "additionalProperties": true } }, "required": [ "stats" ] } ] }, "example": { "trend": { "averagePrice": 1, "currentPrice": 1, "direction": "up", "highestPrice": 1, "history": [ { "date": "string", "price": 1 } ], "lowestPrice": 1, "priceChange30d": 1, "priceChangePct30d": 1, "slug": "string" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/prices/trends`. Query params: `drops`, `slug`.", "parameters": [ { "name": "drops", "in": "query", "required": false, "description": "drops parameter.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "slug", "in": "query", "required": false, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/products": { "get": { "operationId": "getProducts", "summary": "List products", "tags": [ "products" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "number" }, "page": { "type": "number" }, "products": { "type": "array", "items": { "type": "object", "properties": { "asin": { "type": "string", "nullable": true }, "category": { "type": "string" }, "categorySlug": { "type": "string" }, "id": { "type": "string" }, "imageUrl": { "type": "string", "nullable": true }, "keySpecs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] } }, "lowestPrice": { "type": "object", "properties": { "amount": { "type": "number" }, "inStock": { "type": "boolean" }, "retailer": { "type": "string" }, "url": { "type": "string" } }, "required": [ "amount", "inStock", "retailer", "url" ], "nullable": true }, "manufacturer": { "type": "string" }, "manufacturerSlug": { "type": "string" }, "mpn": { "type": "string", "nullable": true }, "name": { "type": "string" }, "priceFreshness": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "refresh_error", "refresh_stale", "no_data", "no_trends", "source_unavailable" ], "nullable": true }, "staleAfterHours": { "type": "number" }, "status": { "type": "string", "enum": [ "fresh", "stale", "unavailable" ] }, "updatedAt": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "staleAfterHours", "status", "updatedAt" ], "nullable": true }, "prices": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number" }, "displayable": { "type": "object", "additionalProperties": true, "nullable": true }, "inStock": { "type": "boolean" }, "retailer": { "type": "string" }, "retailerSlug": { "type": "string" }, "source": { "type": "string", "enum": [ "retailer", "amazon" ], "nullable": true }, "updatedAt": { "type": "object", "additionalProperties": true, "nullable": true }, "url": { "type": "string" } }, "required": [ "amount", "inStock", "retailer", "retailerSlug", "url" ] } }, "rating": { "type": "number" }, "reviewCount": { "type": "number" }, "salesRank": { "type": "number", "nullable": true }, "sharedIdentifiers": { "type": "object", "properties": { "asin": { "type": "boolean" }, "mpn": { "type": "boolean" } }, "required": [ "asin", "mpn" ], "nullable": true }, "slug": { "type": "string" }, "specs": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } }, "required": [ "asin", "category", "categorySlug", "id", "imageUrl", "keySpecs", "lowestPrice", "manufacturer", "manufacturerSlug", "mpn", "name", "prices", "rating", "reviewCount", "salesRank", "slug", "specs" ] } }, "total": { "type": "number" } }, "required": [ "limit", "page", "products", "total" ] }, "example": { "limit": 1, "page": 1, "products": [ { "asin": "string", "category": "string", "categorySlug": "string", "id": "string", "imageUrl": "string", "keySpecs": [ { "label": "string", "value": "string" } ], "lowestPrice": { "amount": 1, "inStock": true, "retailer": "string", "url": "string" }, "manufacturer": "string", "manufacturerSlug": "string", "mpn": "string", "name": "string", "priceFreshness": { "reason": "refresh_error", "staleAfterHours": 1, "status": "fresh", "updatedAt": {} }, "prices": [ { "amount": 1, "displayable": {}, "inStock": true, "retailer": "string", "retailerSlug": "string", "source": "retailer", "updatedAt": {}, "url": "string" } ], "rating": 1, "reviewCount": 1, "salesRank": 1, "sharedIdentifiers": { "asin": true, "mpn": true }, "slug": "string", "specs": {} } ], "total": 1 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/products`. Query params: `category`, `slugs`.", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category slug.", "schema": { "type": "string" } }, { "name": "slugs", "in": "query", "required": false, "description": "slugs parameter.", "schema": { "type": "string" } } ] } }, "/api/products/{slug}": { "get": { "operationId": "getProductsSlug", "summary": "Get a product by slug", "tags": [ "products" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "asin": { "type": "string", "nullable": true }, "category": { "type": "string" }, "categorySlug": { "type": "string" }, "id": { "type": "string" }, "imageUrl": { "type": "string", "nullable": true }, "keySpecs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] } }, "lowestPrice": { "type": "object", "properties": { "amount": { "type": "number" }, "inStock": { "type": "boolean" }, "retailer": { "type": "string" }, "url": { "type": "string" } }, "required": [ "amount", "inStock", "retailer", "url" ], "nullable": true }, "manufacturer": { "type": "string" }, "manufacturerSlug": { "type": "string" }, "mpn": { "type": "string", "nullable": true }, "name": { "type": "string" }, "priceFreshness": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "refresh_error", "refresh_stale", "no_data", "no_trends", "source_unavailable" ], "nullable": true }, "staleAfterHours": { "type": "number" }, "status": { "type": "string", "enum": [ "fresh", "stale", "unavailable" ] }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "staleAfterHours", "status", "updatedAt" ], "nullable": true }, "prices": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number" }, "displayable": { "type": "boolean", "nullable": true }, "inStock": { "type": "boolean" }, "retailer": { "type": "string" }, "retailerSlug": { "type": "string" }, "source": { "type": "string", "enum": [ "retailer", "amazon" ], "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "url": { "type": "string" } }, "required": [ "amount", "inStock", "retailer", "retailerSlug", "url" ] } }, "rating": { "type": "number" }, "reviewCount": { "type": "number" }, "salesRank": { "type": "number", "nullable": true }, "sharedIdentifiers": { "type": "object", "properties": { "asin": { "type": "boolean" }, "mpn": { "type": "boolean" } }, "required": [ "asin", "mpn" ], "nullable": true }, "slug": { "type": "string" }, "specs": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } }, "required": [ "asin", "category", "categorySlug", "id", "imageUrl", "keySpecs", "lowestPrice", "manufacturer", "manufacturerSlug", "mpn", "name", "prices", "rating", "reviewCount", "salesRank", "slug", "specs" ] }, "example": { "asin": "string", "category": "string", "categorySlug": "string", "id": "string", "imageUrl": "string", "keySpecs": [ { "label": "string", "value": "string" } ], "lowestPrice": { "amount": 1, "inStock": true, "retailer": "string", "url": "string" }, "manufacturer": "string", "manufacturerSlug": "string", "mpn": "string", "name": "string", "priceFreshness": { "reason": "refresh_error", "staleAfterHours": 1, "status": "fresh", "updatedAt": "string" }, "prices": [ { "amount": 1, "displayable": true, "inStock": true, "retailer": "string", "retailerSlug": "string", "source": "retailer", "updatedAt": "string", "url": "string" } ], "rating": 1, "reviewCount": 1, "salesRank": 1, "sharedIdentifiers": { "asin": true, "mpn": true }, "slug": "string", "specs": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/products/{slug}`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/products/{slug}/similar": { "get": { "operationId": "getProductsSlugSimilar", "summary": "Returns up to 4 similar products scored by category-specific attributes:", "tags": [ "products" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "products" ] }, { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "asin": { "type": "string", "nullable": true }, "category": { "type": "string" }, "categorySlug": { "type": "string" }, "id": { "type": "string" }, "imageUrl": { "type": "string", "nullable": true }, "keySpecs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] } }, "lowestPrice": { "type": "object", "properties": { "amount": { "type": "number" }, "inStock": { "type": "boolean" }, "retailer": { "type": "string" }, "url": { "type": "string" } }, "required": [ "amount", "inStock", "retailer", "url" ], "nullable": true }, "manufacturer": { "type": "string" }, "manufacturerSlug": { "type": "string" }, "mpn": { "type": "string", "nullable": true }, "name": { "type": "string" }, "priceFreshness": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "refresh_error", "refresh_stale", "no_data", "no_trends", "source_unavailable" ], "nullable": true }, "staleAfterHours": { "type": "number" }, "status": { "type": "string", "enum": [ "fresh", "stale", "unavailable" ] }, "updatedAt": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "staleAfterHours", "status", "updatedAt" ], "nullable": true }, "prices": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number" }, "displayable": { "type": "object", "additionalProperties": true, "nullable": true }, "inStock": { "type": "boolean" }, "retailer": { "type": "string" }, "retailerSlug": { "type": "string" }, "source": { "type": "string", "enum": [ "retailer", "amazon" ], "nullable": true }, "updatedAt": { "type": "object", "additionalProperties": true, "nullable": true }, "url": { "type": "string" } }, "required": [ "amount", "inStock", "retailer", "retailerSlug", "url" ] } }, "rating": { "type": "number" }, "reviewCount": { "type": "number" }, "salesRank": { "type": "number", "nullable": true }, "sharedIdentifiers": { "type": "object", "properties": { "asin": { "type": "boolean" }, "mpn": { "type": "boolean" } }, "required": [ "asin", "mpn" ], "nullable": true }, "slug": { "type": "string" }, "specs": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } }, "required": [ "asin", "category", "categorySlug", "id", "imageUrl", "keySpecs", "lowestPrice", "manufacturer", "manufacturerSlug", "mpn", "name", "prices", "rating", "reviewCount", "salesRank", "slug", "specs" ] } } }, "required": [ "products" ] } ] }, "example": { "products": [ {} ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "- Same category (required) - Same socket / chipset family (CPUs, motherboards, coolers) - Similar price range (±50%) - Recent release date (prefer same generation) - Cross-brand alternatives at comparable specs The scoring is done in SQL using the JSONB specs column so the DB returns only the top candidates, avoiding full-category loads.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/products/categories": { "get": { "operationId": "getProductsCategories", "summary": "List product categories", "tags": [ "products" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "count": { "type": "number" }, "icon": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "count", "icon", "key", "label", "slug" ] } } }, "required": [ "categories" ] }, "example": { "categories": [ { "count": 1, "icon": "string", "key": "string", "label": "string", "slug": "string" } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/products/categories`." } }, "/api/products/filters": { "get": { "operationId": "getProductsFilters", "summary": "PLA-3221 — category filter definitions for client surfaces", "tags": [ "products" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "count": { "type": "object", "additionalProperties": true }, "label": { "type": "object", "additionalProperties": true }, "value": { "type": "object", "additionalProperties": true } }, "required": [ "label", "value" ] } }, "type": { "type": "string", "enum": [ "checkbox" ] } }, "required": [ "key", "label", "options", "type" ] }, { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "max": { "type": "number" }, "min": { "type": "number" }, "step": { "type": "number" }, "type": { "type": "string", "enum": [ "range" ] }, "unit": { "type": "string" } }, "required": [ "key", "label", "max", "min", "step", "type", "unit" ] }, { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "boolean" ] } }, "required": [ "key", "label", "type" ] } ] } } }, "required": [ "filters" ] }, "example": { "filters": [ { "key": "string", "label": "string", "options": [ { "count": {}, "label": {}, "value": {} } ], "type": "checkbox" } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "The category page gets its `FilterDef[]` from the server component (it can await `getCachedCategoryFilterDefs` directly). The build picker cannot: it is a client dialog mounted inside `/build`, so it needs the same definitions over the wire to render real facets instead of deriving a narrow, wrong facet set from whichever page of results happens to be loaded. This is deliberately a thin read of the SAME cached accessor the category page uses — one derivation of the facet set, one 6-hour `unstable_cache` window (PLA-2818), no extra full-category Prisma scan per picker open.", "parameters": [ { "name": "category", "in": "query", "required": true, "description": "Category slug.", "schema": { "type": "string" } } ] } }, "/api/products/search": { "get": { "operationId": "getProductsSearch", "summary": "lightweight autocomplete search", "tags": [ "products" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "results" ] }, "example": { "results": [ {} ] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Returns minimal product data for search dialogs (compare page, etc.) so clients never need to load the full 56K product dataset. Query params: q — search query (min 2 chars, required) category — optional category slug filter exclude — optional comma-separated slugs to exclude limit — max results (default 12, max 50)", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category slug.", "schema": { "type": "string" } }, { "name": "exclude", "in": "query", "required": false, "description": "exclude parameter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search query.", "schema": { "type": "string" } } ] } }, "/api/reviews": { "get": { "operationId": "getReviews", "summary": "List reviews", "tags": [ "reviews" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total": { "type": "number" } }, "required": [ "reviews", "total" ] }, "example": { "reviews": [ {} ], "total": 1 } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/reviews`. Query params: `productId`, `productSlug`, `sort`.", "parameters": [ { "name": "productId", "in": "query", "required": false, "description": "productId parameter.", "schema": { "type": "string" } }, { "name": "productSlug", "in": "query", "required": false, "description": "productSlug parameter.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order.", "schema": { "type": "string" } } ] }, "post": { "operationId": "postReviews", "summary": "Create a review", "tags": [ "reviews" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "avatarUrl": { "type": "string", "nullable": true }, "body": { "type": "string" }, "cons": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "displayName": { "type": "string", "nullable": true }, "helpful": { "type": "number" }, "id": { "type": "string" }, "productId": { "type": "string" }, "pros": { "type": "array", "items": { "type": "string" } }, "rating": { "type": "number" }, "title": { "type": "string" }, "userId": { "type": "string" }, "username": { "type": "string" }, "verified": { "type": "boolean" } }, "required": [ "avatarUrl", "body", "cons", "createdAt", "displayName", "helpful", "id", "productId", "pros", "rating", "title", "userId", "username", "verified" ] }, "example": { "avatarUrl": "string", "body": "string", "cons": [ "string" ], "createdAt": "string", "displayName": "string", "helpful": 1, "id": "string", "productId": "string", "pros": [ "string" ], "rating": 1, "title": "string", "userId": "string", "username": "string", "verified": true } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/reviews`.", "security": [ { "supabaseSession": [] } ] } }, "/api/saved-items": { "get": { "operationId": "getSavedItems", "summary": "returns all saved items for authenticated user", "tags": [ "saved-items" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "productSlug": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "category", "createdAt", "id", "productSlug", "userId" ] } } }, "required": [ "items" ] }, "example": { "items": [ { "category": "string", "createdAt": "2026-04-10T12:00:00.000Z", "id": "string", "productSlug": "string", "userId": "string" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/saved-items`." }, "post": { "operationId": "postSavedItems", "summary": "saves a product (idempotent, 200 if already exists", "tags": [ "saved-items" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "productSlug": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "category", "createdAt", "id", "productSlug", "userId" ] }, "example": { "category": "string", "createdAt": "2026-04-10T12:00:00.000Z", "id": "string", "productSlug": "string", "userId": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/saved-items`." } }, "/api/saved-items/{slug}": { "delete": { "operationId": "deleteSavedItemsSlug", "summary": "removes a saved item", "tags": [ "saved-items" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/saved-items/{slug}`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/search": { "get": { "operationId": "getSearch", "summary": "Search products, guides, and community content", "tags": [ "search" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "builds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "useCase": { "type": "string" } }, "required": [ "id", "slug", "title", "useCase" ] } }, "forums": { "type": "array", "items": { "type": "object", "properties": { "categorySlug": { "type": "string" }, "id": { "type": "string" }, "replyCount": { "type": "number" }, "title": { "type": "string" } }, "required": [ "categorySlug", "id", "replyCount", "title" ] } }, "guides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "useCase": { "type": "string" } }, "required": [ "id", "slug", "title", "useCase" ] } }, "products": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "id": { "type": "string" }, "imageUrl": { "type": "string", "nullable": true }, "lowestPrice": { "type": "number", "nullable": true }, "manufacturer": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "category", "id", "imageUrl", "lowestPrice", "manufacturer", "name", "slug" ] } } }, "required": [ "builds", "forums", "guides", "products" ] }, "example": { "builds": [ { "id": "string", "slug": "string", "title": "string", "useCase": "string" } ], "forums": [ { "categorySlug": "string", "id": "string", "replyCount": 1, "title": "string" } ], "guides": [ { "id": "string", "slug": "string", "title": "string", "useCase": "string" } ], "products": [ { "category": "string", "id": "string", "imageUrl": "string", "lowestPrice": 1, "manufacturer": "string", "name": "string", "slug": "string" } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/search`. Query params: `q`, `type`.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Free-text search query.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "type parameter.", "schema": { "type": "string" } } ] } }, "/api/seed-benchmarks": { "post": { "operationId": "postSeedBenchmarks", "summary": "Seed benchmark data", "tags": [ "seed-benchmarks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "resultsCreated": { "type": "number" }, "skipped": { "type": "number" }, "suitesCreated": { "type": "number" } }, "required": [ "message", "resultsCreated", "skipped", "suitesCreated" ] }, "example": { "message": "string", "resultsCreated": 1, "skipped": 1, "suitesCreated": 1 } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/seed-benchmarks`." } }, "/api/trends": { "get": { "operationId": "getTrends", "summary": "List trend summaries", "tags": [ "trends" ], "responses": { "200": { "description": "OK" } }, "description": "?category=CPU&limit=50&cursor=some-slug&days=180&slug=specific-slug", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category slug.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "cursor parameter.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "days parameter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "slug", "in": "query", "required": false, "description": "Resource slug.", "schema": { "type": "string" } } ] } }, "/api/users/{username}": { "get": { "operationId": "getUsersUsername", "summary": "Get a public user profile", "tags": [ "users" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "builds": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "forumActivity": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "user": { "type": "object", "additionalProperties": true } }, "required": [ "builds", "forumActivity", "user" ] }, "example": { "builds": [ {} ], "forumActivity": [ {} ], "user": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/users/{username}`.", "parameters": [ { "name": "username", "in": "path", "required": true, "description": "Public username.", "schema": { "type": "string" } } ] } }, "/api/users/profile": { "patch": { "operationId": "patchUsersProfile", "summary": "Patch users", "tags": [ "users" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "additionalProperties": true } }, "required": [ "user" ] }, "example": { "user": {} } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/users/profile`.", "security": [ { "supabaseSession": [] } ] } }, "/api/v1/builds": { "get": { "operationId": "getV1Builds", "summary": "List published community builds for external API clients", "tags": [ "v1" ], "responses": { "200": { "description": "OK" } }, "description": "Requires a bearer API key with the `builds:read` scope. Supports use-case, price-range, sort, and pagination filters. Only non-DRAFT, moderation-approved builds are returned (`INDEXABLE_BUILD_WHERE`, PLA-3684).", "parameters": [ { "name": "maxPrice", "in": "query", "required": false, "description": "Price filter or target value.", "schema": { "type": "number" } }, { "name": "minPrice", "in": "query", "required": false, "description": "Price filter or target value.", "schema": { "type": "number" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order.", "schema": { "type": "string" } }, { "name": "useCase", "in": "query", "required": false, "description": "useCase parameter.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/builds/{id}": { "get": { "operationId": "getV1BuildsId", "summary": "Get one published build by UUID or slug for external API clients", "tags": [ "v1" ], "responses": { "200": { "description": "OK" } }, "description": "Requires a bearer API key with the `builds:read` scope. Accepts either the build UUID or slug in the path and returns public author, photo, and part summary fields.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/keys": { "get": { "operationId": "getV1Keys", "summary": "List API keys for the signed-in user", "tags": [ "v1" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "keys" ] }, "example": { "keys": [ {} ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Requires a Supabase-authenticated session rather than a bearer API key. Returns key metadata only; the raw secret is never returned from this read endpoint.", "security": [ { "supabaseSession": [] } ] }, "post": { "operationId": "postV1Keys", "summary": "Create a new API key for the signed-in user", "tags": [ "v1" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "warning": { "type": "string" } }, "required": [ "key", "warning" ] }, "example": { "key": "string", "warning": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Requires a Supabase-authenticated session. The raw key is returned only once in the creation response, so clients must store it immediately.", "security": [ { "supabaseSession": [] } ] }, "delete": { "operationId": "deleteV1Keys", "summary": "Revoke one API key owned by the signed-in user", "tags": [ "v1" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Requires a Supabase-authenticated session. Expects the key id in the `id` query parameter and performs a soft revoke by setting `revokedAt`.", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Resource identifier.", "schema": { "type": "string" } } ], "security": [ { "supabaseSession": [] } ] } }, "/api/v1/prices": { "get": { "operationId": "getV1Prices", "summary": "Get current retailer prices and recent price history for one product", "tags": [ "v1" ], "responses": { "200": { "description": "OK" } }, "description": "Requires a bearer API key with the `prices:read` scope. The `slug` query parameter is required. Current prices come from the ProductPrice table, while historical data comes from `AsinPriceSnapshot`. Rows from the store price pilot stores are left out: we show prices read from those stores' pages on planmypc.com but do not redistribute them to third parties (docs/infra/store-price-pilot.md).", "parameters": [ { "name": "slug", "in": "query", "required": false, "description": "Resource slug.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/products": { "get": { "operationId": "getV1Products", "summary": "List catalog products — DB-backed with server-side filtering, sorting, pagination", "tags": [ "v1" ], "responses": { "200": { "description": "OK" } }, "description": "Requires a bearer API key with the `products:read` scope. Each product's `lowestPrice` is the amount its product page headlines and the retailer offering it, or null when the page shows no price. Prices read from the store price pilot stores are never returned. `minPrice`, `maxPrice` and the price sorts read a stored key instead, and `lowestPrice.amount` is never lower than that key (docs/public-api.md).", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category slug.", "schema": { "type": "string" } }, { "name": "manufacturer", "in": "query", "required": false, "description": "manufacturer parameter.", "schema": { "type": "string" } }, { "name": "maxPrice", "in": "query", "required": false, "description": "Price filter or target value.", "schema": { "type": "number" } }, { "name": "minPrice", "in": "query", "required": false, "description": "Price filter or target value.", "schema": { "type": "number" } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search query.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/products/{slug}": { "get": { "operationId": "getV1ProductsSlug", "summary": "Get one catalog product by slug for external API clients", "tags": [ "v1" ], "responses": { "200": { "description": "OK" } }, "description": "Requires a bearer API key with the `products:read` scope. Looks up the product by slug from the database and returns public product fields plus current retailer prices. Rows from the store price pilot stores are left out: we show prices read from those stores' pages on planmypc.com but do not redistribute them (docs/infra/store-price-pilot.md).", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/api/wishlist": { "get": { "operationId": "getWishlist", "summary": "List wishlist items", "tags": [ "wishlist" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "productId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "createdAt", "id", "productId", "userId" ] } } }, "required": [ "items" ] }, "example": { "items": [ { "createdAt": "2026-04-10T12:00:00.000Z", "id": "string", "productId": "string", "userId": "string" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/wishlist`." }, "post": { "operationId": "postWishlist", "summary": "Add a wishlist item", "tags": [ "wishlist" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "productId": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "createdAt", "id", "productId", "userId" ] }, "example": { "createdAt": "2026-04-10T12:00:00.000Z", "id": "string", "productId": "string", "userId": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/wishlist`." }, "delete": { "operationId": "deleteWishlist", "summary": "Remove a wishlist item", "tags": [ "wishlist" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "example": { "error": "string" } } } } }, "description": "Auto-generated from the route handler for `/api/wishlist`. Query params: `slug`.", "parameters": [ { "name": "slug", "in": "query", "required": true, "description": "Resource slug.", "schema": { "type": "string" } } ] } } } }