{"openapi":"3.1.0","info":{"title":"Style Guide Generator API","version":"1.0.0","description":"Programmatic access to all style guide generation features. Generate and refine palettes, export tokens, and capture screenshots."},"servers":[{"url":"https://styleguide.ideaplaces.com/api/v1","description":"Production"},{"url":"https://styleguide.ideaplaces.dev/api/v1","description":"Development"},{"url":"http://localhost:7392/api/v1","description":"Local"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key (sg_live_* or sg_test_*)"}},"schemas":{"RegisterResponse":{"type":"object","properties":{"apiKey":{"type":"string","description":"Full API key (sg_live_* or sg_test_*). Returned once, store securely."},"userId":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"plan":{"type":"string"},"claimUrl":{"type":"string","format":"uri"},"message":{"type":"string"}},"required":["apiKey","userId","name","plan","claimUrl","message"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","description":"Machine-readable error code (e.g. UNAUTHORIZED, NOT_FOUND, RATE_LIMIT)"},"retryAfter":{"type":"integer","description":"Seconds until next request allowed (rate limit errors only)"}},"required":["error","code"]},"RegisterRequest":{"type":"object","properties":{"name":{"type":"string","description":"Display name (defaults to \"Anonymous\")"},"email":{"type":"string","description":"Email address (optional, placeholder generated if absent)"},"context":{"type":"string","maxLength":500,"description":"Summary of how the key will be used (up to 500 chars)"}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","nullable":true,"format":"date-time"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","name","prefix","createdAt","lastUsedAt","expiresAt"]},"ApiKeyGenerated":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"key":{"type":"string","description":"Full key (sg_live_* or sg_test_*). Returned once."}},"required":["key"]}]},"CreateApiKeyRequest":{"type":"object","properties":{"name":{"type":"string"},"expiresAt":{"type":"string","nullable":true}},"additionalProperties":{"nullable":true}},"GenerateResponse":{"type":"object","properties":{"conversationId":{"type":"string","format":"uuid"},"message":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"role":{"type":"string"},"type":{"type":"string"},"content":{"type":"string"},"variations":{"type":"array","items":{"$ref":"#/components/schemas/Palette"}},"versionIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","role","type","content","variations","versionIds"]},"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"versionNumber":{"type":"integer"}},"required":["id","versionNumber"]}}},"required":["conversationId","message","versions"]},"Palette":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable palette name"},"description":{"type":"string","description":"Short description of mood and intent"},"rationale":{"type":"string","description":"Explanation of design decisions"},"colors":{"type":"object","properties":{"primary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"primaryLight":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"primaryDark":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"secondary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"secondaryLight":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"secondaryDark":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"backgroundAlt":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"surface":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"foreground":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"foregroundMuted":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"border":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"borderLight":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"success":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"warning":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"error":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"info":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"required":["primary","primaryLight","primaryDark","secondary","secondaryLight","secondaryDark","accent","background","backgroundAlt","surface","foreground","foregroundMuted","border","borderLight","success","warning","error","info"]},"typography":{"type":"object","properties":{"fontFamily":{"type":"string"},"fontFamilyHeading":{"type":"string"},"fontFamilyMono":{"type":"string"},"fontWeightBody":{"type":"number"},"fontWeightHeading":{"type":"number"},"lineHeightBody":{"type":"number"},"lineHeightHeading":{"type":"number"},"scale":{"type":"array","items":{"type":"number"}}},"required":["fontFamily","fontFamilyHeading","fontFamilyMono","fontWeightBody","fontWeightHeading","lineHeightBody","lineHeightHeading","scale"]},"spacing":{"type":"object","properties":{"baseUnit":{"type":"number"},"scale":{"type":"array","items":{"type":"number"}}},"required":["baseUnit","scale"]},"iconStyle":{"type":"string","enum":["outlined","filled","rounded"]},"borderRadius":{"type":"string"},"shadowStyle":{"type":"string","enum":["none","subtle","medium","elevated","dramatic"]}},"required":["name","description","rationale","colors","typography","spacing","iconStyle","borderRadius","shadowStyle"]},"GenerateRequest":{"type":"object","properties":{"prompt":{"type":"string","description":"Brand description to generate a style guide from (1-5000 chars)"}},"additionalProperties":{"nullable":true}},"SelectRequest":{"type":"object","properties":{"variationIndex":{"type":"number"},"messageId":{"type":"string"}},"additionalProperties":{"nullable":true}},"RefineRequest":{"type":"object","properties":{"instruction":{"type":"string"}},"additionalProperties":{"nullable":true}},"RollbackRequest":{"type":"object","properties":{"targetVersionId":{"type":"string"}},"additionalProperties":{"nullable":true}},"PromptsResponse":{"type":"object","properties":{"version":{"type":"string"},"systemPrompt":{"type":"string"},"generateTemplate":{"type":"string"},"refineTemplate":{"type":"string"},"schema":{"nullable":true}},"required":["version","systemPrompt","generateTemplate","refineTemplate"]},"Version":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"versionNumber":{"type":"integer"},"conversationId":{"type":"string","format":"uuid"},"palette":{"nullable":true,"description":"See the Palette component schema for shape"},"changeSummary":{"type":"string","nullable":true},"parentVersionId":{"type":"string","nullable":true,"format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","versionNumber","conversationId","changeSummary","parentVersionId","createdAt"]}},"parameters":{}},"paths":{"/auth/register":{"post":{"tags":["Auth"],"summary":"Register a new free-tier account and receive an API key","description":"Public endpoint, no auth required. Designed for zero-friction use from Claude, ChatGPT, or any AI assistant.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}},"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"409":{"description":"Email already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many registrations from this IP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api-keys":{"get":{"tags":["API Keys"],"summary":"List API keys for the authenticated user","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}},"required":["keys"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["API Keys"],"summary":"Create a new API key","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyGenerated"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api-keys/{keyId}":{"delete":{"tags":["API Keys"],"summary":"Revoke an API key","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"keyId","in":"path"}],"responses":{"204":{"description":"Revoked"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chat/generate":{"post":{"tags":["Chat"],"summary":"Generate 4 palette variations from a brand description","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}}},"responses":{"201":{"description":"Generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}":{"get":{"tags":["Conversations"],"summary":"Get a conversation with messages and active palette","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Conversations"],"summary":"Soft-delete a conversation","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/select":{"post":{"tags":["Conversations"],"summary":"Select one of 4 variations as the active version","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelectRequest"}}}},"responses":{"200":{"description":"Selected","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/refine":{"post":{"tags":["Conversations"],"summary":"Refine the active palette with a natural-language instruction","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefineRequest"}}}},"responses":{"201":{"description":"Refined","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/rollback":{"post":{"tags":["Conversations"],"summary":"Set a previous version as the active version","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RollbackRequest"}}}},"responses":{"200":{"description":"Rolled back","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/palette":{"get":{"tags":["Conversations"],"summary":"Get the active palette for a conversation","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string"},"versionId":{"type":"string"},"versionNumber":{"type":"integer"},"palette":{"nullable":true}},"required":["conversationId","versionId","versionNumber"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/versions":{"get":{"tags":["Conversations"],"summary":"List all versions for a conversation","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/tree":{"get":{"tags":["Conversations"],"summary":"Get the exploration tree structure","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/prompts":{"get":{"tags":["Conversations"],"summary":"Get the reconstructed LLM prompt chain for this conversation","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/export":{"get":{"tags":["Export"],"summary":"Export the active palette as a ZIP of all 8 formats","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"versionId","in":"query"}],"responses":{"200":{"description":"ZIP archive","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/export/{format}":{"get":{"tags":["Export"],"summary":"Export the active palette as a single file in the requested format","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"format","in":"path"},{"schema":{"type":"string"},"required":false,"name":"versionId","in":"query"}],"responses":{"200":{"description":"File content","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Unsupported format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}/screenshot":{"get":{"tags":["Screenshots"],"summary":"Capture a PNG screenshot of the style guide","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"conversationId","in":"path"},{"schema":{"type":"string","example":"components"},"required":false,"name":"view","in":"query"},{"schema":{"type":"string","example":"web"},"required":false,"name":"platform","in":"query"},{"schema":{"type":"string"},"required":false,"name":"fullPage","in":"query"},{"schema":{"type":"string"},"required":false,"name":"versionId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"width","in":"query"}],"responses":{"200":{"description":"PNG image","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/prompts":{"get":{"tags":["Prompts"],"summary":"Get the system prompt, generate/refine templates, and JSON schema","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/versions/{versionId}":{"get":{"tags":["Versions"],"summary":"Get a single version by ID","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Version"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}