{"openapi":"3.0.0","info":{"title":"IcoGenie API","version":"1.0.0","description":"Production-ready SVG icon generator powered by AI. Built for agents, API-friendly, developer-first. Generate icons from text descriptions with CLI tool, REST API, and web interface.","contact":{"name":"IcoGenie Support","url":"https://www.icogenie.xyz"},"license":{"name":"Proprietary","url":"https://www.icogenie.xyz/terms"}},"servers":[{"url":"https://www.icogenie.xyz","description":"Production server"}],"tags":[{"name":"Generation","description":"Icon generation endpoints"},{"name":"Auth","description":"Authentication endpoints"},{"name":"Credits","description":"Credit management endpoints"},{"name":"Library","description":"Icon library endpoints"},{"name":"CLI","description":"CLI-specific endpoints"}],"security":[{"cookieAuth":[]},{"bearerAuth":[]}],"paths":{"/api/generate-preview":{"post":{"tags":["Generation"],"summary":"Generate icon preview","description":"Generate a watermarked preview of an icon from a text description. Costs 1 credit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"Text description of the icon to generate","example":"A rocket ship launching into space"},"variations":{"type":"integer","enum":[1,2,4],"default":1,"description":"Number of variations to generate"},"style":{"type":"string","enum":["solid","outline"],"default":"solid","description":"Icon style"},"referenceImage":{"type":"object","description":"Optional reference image for style matching","properties":{"data":{"type":"string","description":"Base64-encoded image data"},"mimeType":{"type":"string","description":"MIME type of the image","example":"image/png"}}}}}}}},"responses":{"200":{"description":"Preview generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","description":"Session ID for downloading"},"preview":{"type":"string","description":"Base64-encoded watermarked preview (first variation)"},"previews":{"type":"array","items":{"type":"string"},"description":"Array of all variation previews"},"normalizedPrompt":{"type":"string","description":"AI-processed prompt"},"description":{"type":"string","description":"AI interpretation"}}}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCreditsError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}},"/api/download":{"get":{"tags":["Generation"],"summary":"Download icon","description":"Download production files for a generated icon. Costs 5 credits for single icons.","parameters":[{"name":"generation_id","in":"query","description":"Generation session ID (for single icons)","schema":{"type":"string","format":"uuid"}},{"name":"bundle_id","in":"query","description":"Bundle ID (for icon bundles)","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"ZIP file containing SVG, PNGs, JSX, and HTML meta","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Authentication required"},"402":{"description":"Insufficient credits"},"404":{"description":"Session expired or not found"}},"security":[{"cookieAuth":[]}]}},"/api/generate-bundle-preview":{"post":{"tags":["Generation"],"summary":"Generate bundle preview","description":"Generate a bundle of 2-20 icons with consistent style. Costs 1 credit for preview (flat rate).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["icons"],"properties":{"icons":{"type":"array","minItems":2,"maxItems":20,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"home"},"description":{"type":"string","example":"A house icon for home navigation"}}}},"style":{"type":"string","enum":["solid","outline"],"default":"solid"},"normalize":{"type":"boolean","default":false,"description":"AI-enhance descriptions before generation"}}}}}},"responses":{"200":{"description":"Bundle preview generated","content":{"application/json":{"schema":{"type":"object","properties":{"bundleId":{"type":"string","format":"uuid"},"icons":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"preview":{"type":"string","description":"Base64 watermarked preview"}}}}}}}}}}}},"/api/regenerate-icon":{"post":{"tags":["Generation"],"summary":"Regenerate icon variation","description":"Regenerate a specific variation with optional custom prompt. Costs 1 credit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","index"],"properties":{"sessionId":{"type":"string","format":"uuid"},"index":{"type":"integer","description":"Variation index to regenerate (0-based)"},"prompt":{"type":"string","description":"Optional custom refinement prompt"}}}}}},"responses":{"200":{"description":"Variation regenerated","content":{"application/json":{"schema":{"type":"object","properties":{"preview":{"type":"string","description":"Base64 watermarked preview of regenerated variation"}}}}}}},"security":[{"cookieAuth":[]}]}},"/api/auth/session":{"get":{"tags":["Auth"],"summary":"Get current session","description":"Get current user session and credit balance","responses":{"200":{"description":"Session info","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}}},"team":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"credits":{"type":"integer"}}}}}},"401":{"description":"Not authenticated"}}}},"/api/credits/checkout":{"post":{"tags":["Credits"],"summary":"Create credit purchase checkout","description":"Create a Stripe Checkout session for purchasing credits","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["package"],"properties":{"package":{"type":"string","enum":["starter","basic","pro","enterprise"],"description":"Credit package to purchase"}}}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Stripe Checkout URL"}}}}}}},"security":[{"cookieAuth":[]}]}},"/api/library":{"get":{"tags":["Library"],"summary":"List library items","description":"Get all icons saved to library","responses":{"200":{"description":"Library items","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LibraryItem"}}}}}},"security":[{"cookieAuth":[]}]}},"/api/library/save":{"post":{"tags":["Library"],"summary":"Save icon to library","description":"Save a generated icon to library for later access","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["generationId"],"properties":{"generationId":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}},"responses":{"200":{"description":"Saved to library"}},"security":[{"cookieAuth":[]}]}},"/api/cli/auth/start":{"post":{"tags":["CLI"],"summary":"Start CLI authentication","description":"Initiate CLI authentication flow. Returns login URL and poll token.","responses":{"200":{"description":"Auth flow started","content":{"application/json":{"schema":{"type":"object","properties":{"login_url":{"type":"string"},"poll_token":{"type":"string"},"expires_in":{"type":"integer"}}}}}}}}},"/api/cli/auth/poll":{"post":{"tags":["CLI"],"summary":"Poll CLI authentication","description":"Poll for CLI authentication approval","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pollToken"],"properties":{"pollToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Auth status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved","expired"]},"access_token":{"type":"string"},"user":{"$ref":"#/components/schemas/UserInfo"}}}}}}}}},"/api/cli/generate":{"post":{"tags":["CLI"],"summary":"CLI icon generation","description":"Generate icon from CLI","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionToken","prompt"],"properties":{"sessionToken":{"type":"string"},"prompt":{"type":"string"},"variations":{"type":"integer","enum":[1,2,4],"default":1},"style":{"type":"string","enum":["solid","outline"],"default":"solid"}}}}}},"responses":{"200":{"description":"Icon generated"}}}},"/api/cli/download":{"post":{"tags":["CLI"],"summary":"CLI icon download","description":"Download icon from CLI","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionToken"],"properties":{"sessionToken":{"type":"string"},"generationId":{"type":"string","format":"uuid"},"bundleId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"ZIP file","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}}}}}},"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"session","description":"HTTP-only cookie session (web clients)"},"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication for CLI/MCP clients. Obtain token via /api/cli/auth/start flow."}},"schemas":{"InsufficientCreditsError":{"type":"object","properties":{"error":{"type":"string","example":"Insufficient credits"},"message":{"type":"string"},"balance":{"type":"integer"},"required":{"type":"integer"}}},"RateLimitError":{"type":"object","properties":{"error":{"type":"string","example":"Rate limit exceeded"},"message":{"type":"string"},"limit":{"type":"integer"},"remaining":{"type":"integer"},"resetAt":{"type":"string","format":"date-time"}}},"LibraryItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"generation_id":{"type":"string","format":"uuid"},"prompt":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["saved","exported"]},"type":{"type":"string","enum":["single","bundle"]},"variations":{"type":"integer"},"style":{"type":"string","enum":["solid","outline"]},"preview_url":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"UserInfo":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"team_id":{"type":"string"},"team_name":{"type":"string"},"credit_balance":{"type":"integer"}}}}}}