{"openapi":"3.1.0","info":{"title":"PhotoGen API & Agent Services","version":"1.0.0","description":"Programmatic API and Model Context Protocol endpoints for PhotoGen Studio — AI photography, curated Lightroom presets, 4K wallpapers, and generative imaging tools.","contact":{"name":"PhotoGen Developer Platform","email":"developers@photogen.com","url":"https://photogen2.vercel.app/developers"},"license":{"name":"Proprietary / Creative Commons","url":"https://photogen2.vercel.app/privacy"}},"x-api-versioning":{"strategy":"url_path_and_header","current_version":"v1","header":"X-API-Version","supported_versions":["v1"],"deprecation_policy":"https://photogen2.vercel.app/developers#versioning-and-deprecation","deprecation_header":"Deprecation","sunset_header":"Sunset","notice_period_days":180},"servers":[{"url":"https://photogen2.vercel.app","description":"Production Server"}],"paths":{"/api/v1/presets":{"get":{"summary":"List & Filter Presets (v1)","description":"Retrieve available Lightroom and color grading preset packs with category tags and asset download URLs.","operationId":"listPresetsV1","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Filter presets by category (e.g. cinematic, portrait, street, landscape)"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Search term across preset titles and descriptions"}],"responses":{"200":{"description":"Array of preset items","headers":{"X-API-Version":{"schema":{"type":"string","example":"1.0"}},"RateLimit-Limit":{"schema":{"type":"integer","example":60}},"RateLimit-Remaining":{"schema":{"type":"integer","example":59}},"RateLimit-Reset":{"schema":{"type":"integer","example":60}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/gallery":{"get":{"summary":"Curated Gallery Captures (v1)","description":"Query curated high-resolution photography items with prompt parameters and lighting metadata.","operationId":"listGalleryV1","parameters":[{"name":"featured","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filter only featured public captures"},{"name":"category","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Gallery captures list","headers":{"X-API-Version":{"schema":{"type":"string","example":"1.0"}},"RateLimit-Limit":{"schema":{"type":"integer","example":60}},"RateLimit-Remaining":{"schema":{"type":"integer","example":59}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GalleryItem"}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/wallpapers":{"get":{"summary":"Ultra-HD 4K Wallpapers (v1)","description":"Retrieve wallpaper collections formatted for desktop and mobile displays.","operationId":"listWallpapersV1","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Wallpaper items list","headers":{"X-API-Version":{"schema":{"type":"string","example":"1.0"}},"RateLimit-Limit":{"schema":{"type":"integer","example":60}},"RateLimit-Remaining":{"schema":{"type":"integer","example":59}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WallpaperItem"}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/blog":{"get":{"summary":"Creative Journal & Insights (v1)","description":"Retrieve articles, color science breakdowns, and tutorials from the PhotoGen journal.","operationId":"listBlogPostsV1","responses":{"200":{"description":"Published articles","headers":{"X-API-Version":{"schema":{"type":"string","example":"1.0"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BlogPost"}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/v1/mcp":{"post":{"summary":"Model Context Protocol (MCP) Endpoint (v1)","description":"JSON-RPC 2.0 / Streamable HTTP endpoint for AI assistants to discover and invoke PhotoGen tools and resources.","operationId":"mcpRpcV1","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":"string","example":"req-1"},"method":{"type":"string","enum":["initialize","tools/list","tools/call","resources/list","resources/read","resources/templates/list","prompts/list","prompts/get","ping"]},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"JSON-RPC response","headers":{"X-API-Version":{"schema":{"type":"string","example":"1.0"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"responses":{"BadRequestError":{"description":"Invalid parameter or malformed request syntax","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"NotFoundError":{"description":"The specified resource was not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"RateLimitedError":{"description":"Too many requests. Agent should throttle using Retry-After header","headers":{"Retry-After":{"schema":{"type":"integer","example":60},"description":"Number of seconds to wait before retrying"},"RateLimit-Limit":{"schema":{"type":"integer","example":60}},"RateLimit-Remaining":{"schema":{"type":"integer","example":0}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"InternalServerError":{"description":"Internal server error occurred while processing request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"schemas":{"ProblemDetails":{"type":"object","description":"RFC 9457 Problem Details for HTTP APIs","properties":{"error":{"type":"object","properties":{"type":{"type":"string","format":"uri","example":"https://photogen2.vercel.app/errors/resource_not_found"},"title":{"type":"string","example":"RESOURCE_NOT_FOUND"},"status":{"type":"integer","example":404},"detail":{"type":"string","example":"The requested API resource does not exist."},"code":{"type":"string","example":"RESOURCE_NOT_FOUND"},"hint":{"type":"string","example":"Check /api/openapi.json or /developers for available routes."},"documentation_url":{"type":"string","format":"uri","example":"https://photogen2.vercel.app/developers"},"invalid_params":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"reason":{"type":"string"}}}}},"required":["title","status","detail","code"]}},"required":["error"]},"Preset":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}},"GalleryItem":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"public_id":{"type":"string"}}}}}},"WallpaperItem":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"public_id":{"type":"string"}}}}}},"BlogPost":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"excerpt":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"}}}}}}