{"openapi":"3.1.0","info":{"title":"LookKind Connector API","version":"2.0.0","description":"An adult, confidence-first visual style consultation. The API creates one identity-preserving recommendation, then revises the portrait and practical plan through an ongoing dialogue."},"servers":[{"url":"https://lookkind.com"}],"paths":{"/api/checkout":{"post":{"operationId":"createLookKindCheckout","summary":"Create a $99 one-time Stripe Checkout session","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"goal":{"type":"string","enum":["hair","makeup","both"],"default":"both"}}}}}},"responses":{"200":{"description":"Checkout created"},"429":{"description":"Hourly checkout request limit reached"},"503":{"description":"Payments or usage protection are not configured"}}}},"/api/v1/style-plan":{"post":{"operationId":"createLookKindConsultation","summary":"Create one opening recommendation from three adult portrait views","description":"Returns one identity-preserving portrait, explanation, routine, and focused product kit. Use style-dialogue to revise it.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["left_image","front_image","right_image","goal","age_confirmed","checkout_session_id"],"properties":{"left_image":{"type":"string","format":"binary","description":"Left-profile JPG, PNG, or WebP, maximum 10 MB."},"front_image":{"type":"string","format":"binary","description":"Front-facing JPG, PNG, or WebP, maximum 10 MB."},"right_image":{"type":"string","format":"binary","description":"Right-profile JPG, PNG, or WebP, maximum 10 MB."},"goal":{"type":"string","enum":["hair","makeup","both"]},"notes":{"type":"string","maxLength":500,"description":"Optional maintenance, workplace, length, color, grooming, or makeup preferences."},"age_confirmed":{"type":"boolean","description":"True only when the subject is 18+ and consented."},"checkout_session_id":{"type":"string","description":"Verified Stripe Checkout Session ID for the LookKind consultation."}}}}}},"responses":{"200":{"description":"Opening consultation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Consultation"}}}},"400":{"description":"Invalid request, age confirmation, or consent"},"402":{"description":"Payment required or not verified"},"413":{"description":"Image exceeds 10 MB"},"415":{"description":"Unsupported image type"},"429":{"description":"Hourly request limit or included consultation limit reached"},"502":{"description":"Generation provider failure; the paid session may be retried"}}}},"/api/v1/style-dialogue":{"post":{"operationId":"reviseLookKindConsultation","summary":"Revise the current portrait and plan from a dialogue message","description":"Preserves the original identity references and unrequested choices while applying the latest user request to the visual, explanation, routine, and products together.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["left_image","front_image","right_image","current_image","user_message","current_recommendation","age_confirmed","checkout_session_id"],"properties":{"left_image":{"type":"string","format":"binary","description":"Left-profile JPG, PNG, or WebP, maximum 10 MB."},"front_image":{"type":"string","format":"binary","description":"Front-facing JPG, PNG, or WebP, maximum 10 MB."},"right_image":{"type":"string","format":"binary","description":"Right-profile JPG, PNG, or WebP, maximum 10 MB."},"current_image":{"type":"string","format":"binary","description":"The latest generated LookKind portrait."},"user_message":{"type":"string","maxLength":500,"description":"The next change requested in the style dialogue."},"history":{"type":"string","description":"JSON array containing up to ten recent user/assistant messages."},"current_recommendation":{"type":"string","description":"JSON object describing the current title, summary, steps, focus areas, and revision."},"goal":{"type":"string","enum":["hair","makeup","both"]},"notes":{"type":"string","maxLength":500},"age_confirmed":{"type":"boolean"},"checkout_session_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Revised recommendation created","content":{"application/json":{"schema":{"type":"object","required":["recommendation","note"],"properties":{"recommendation":{"$ref":"#/components/schemas/Recommendation"},"note":{"type":"string"}}}}}},"400":{"description":"Invalid message, images, age confirmation, or consent"},"402":{"description":"Payment required or not verified"},"409":{"description":"Opening plan required or another generation is already running"},"429":{"description":"Hourly request limit or 10-revision consultation limit reached"},"502":{"description":"Revision provider failure; the prior revision remains valid"}}}}},"components":{"schemas":{"Consultation":{"type":"object","required":["consultation_id","created_at","recommendation","note"],"properties":{"consultation_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"recommendation":{"$ref":"#/components/schemas/Recommendation"},"note":{"type":"string"}}},"Recommendation":{"type":"object","required":["title","summary","assistant_message","image_data_url","steps","products","focus_areas","revision"],"properties":{"title":{"type":"string"},"summary":{"type":"string"},"assistant_message":{"type":"string"},"image_data_url":{"type":["string","null"],"description":"Base64 JPEG data URL. Null only in a clearly labeled local demo without generation."},"revision":{"type":"integer","minimum":1},"steps":{"type":"array","minItems":4,"maxItems":6,"items":{"type":"string"}},"focus_areas":{"type":"array","minItems":3,"maxItems":3,"items":{"$ref":"#/components/schemas/FocusArea"}},"products":{"type":"array","minItems":3,"maxItems":3,"items":{"$ref":"#/components/schemas/Product"}}}},"FocusArea":{"type":"object","required":["label","description","observation","impact","projected_change","action","x","y","side"],"properties":{"label":{"type":"string"},"description":{"type":"string"},"observation":{"type":"string","description":"Direct, non-diagnostic description of what is visibly supported by the source photos."},"impact":{"type":"string","description":"Why the visible feature matters to the portrait presentation."},"projected_change":{"type":"string","description":"What the generated projection changes using presentation choices or an explicitly requested hypothetical cosmetic preview."},"action":{"type":"string","description":"Practical next action; not medical advice."},"x":{"type":"number","minimum":8,"maximum":92,"description":"Horizontal marker position as a percentage of the original front image."},"y":{"type":"number","minimum":8,"maximum":92,"description":"Vertical marker position as a percentage of the original front image."},"side":{"type":"string","enum":["left","right"],"description":"Preferred side for the visual callout."}}},"Product":{"type":"object","required":["brand","name","purpose","retailer","price","product_url","image_url"],"properties":{"brand":{"type":"string"},"name":{"type":"string"},"purpose":{"type":"string"},"retailer":{"type":"string"},"price":{"type":"string"},"product_url":{"type":"string","format":"uri"},"image_url":{"type":"string","format":"uri"}}}}}}