{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Predict Hair simulation API","version":"1.0.0","description":"Runs the same fictional hair-color inheritance game as the website. Percentages are game outputs, not validated genetic probabilities. Missing family colors are UNDEFINED. An entirely unknown family yields needs_input and no distribution. Inputs are processed in memory, without application storage, logging or outgoing requests; responses do not echo the family and are not cached."},"servers":[{"url":"https://www.predict-hair.com"}],"externalDocs":{"description":"Usage, model rules and canonical resources","url":"https://www.predict-hair.com/for-ai-assistants"},"paths":{"/api/v1/predict":{"post":{"operationId":"calculateHairColorGame","summary":"Calculate the hair-color game distribution","description":"Public endpoint without a key or cookies. No special User-Agent is required. Send UTF-8 JSON (at most 1024 bytes) in the body, not in URL query parameters. Colors use the documented uppercase codes. Invalid or extra properties are rejected; errors are in English. The browser calculator continues to compute locally.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionRequest"},"example":{"family":{"mother":"BROWN","father":"BLOND"},"locale":"en"}}}},"responses":{"200":{"description":"Distribution calculated, or more input is needed.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionResponse"},"examples":{"calculated":{"value":{"apiVersion":"1","modelVersion":"hair-game-v1","purpose":"entertainment","scientificallyValidated":false,"locale":"en","status":"ok","unit":"percent","results":[{"color":"BLACK","label":"Black","percentage":0},{"color":"BROWN","label":"Brown","percentage":57.14},{"color":"RED","label":"Red","percentage":14.29},{"color":"BLOND","label":"Blond","percentage":23.81},{"color":"STBLOND","label":"Light blond","percentage":4.76}],"explanation":"For fun: these percentages describe the model’s rules, not your baby’s real chances. This calculation cannot identify genes or determine hair color at birth.","sourceUrl":"https://www.predict-hair.com/","documentationUrl":"https://www.predict-hair.com/for-ai-assistants"}},"needsInput":{"value":{"apiVersion":"1","modelVersion":"hair-game-v1","purpose":"entertainment","scientificallyValidated":false,"locale":"en","status":"needs_input","unit":"percent","results":null,"explanation":"Choose at least one hair color to explore the model. No result is shown while all colors are unknown.","sourceUrl":"https://www.predict-hair.com/","documentationUrl":"https://www.predict-hair.com/for-ai-assistants"}}}}}},"400":{"description":"Send family colors in the JSON body, without URL query parameters. Send a valid UTF-8 JSON object.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"The JSON body must not exceed 1024 bytes.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Use Content-Type: application/json and an uncompressed UTF-8 body.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Provide a family object using the documented fields and uppercase color codes, and an optional supported locale. Additional fields are not accepted.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"The calculation could not be completed.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"options":{"operationId":"hairColorApiCors","summary":"CORS preflight","responses":{"204":{"description":"POST allowed with Content-Type: application/json. No cookies or credentials.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"private, no-store, max-age=0"},"Content-Language":{"schema":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}}}}}}},"components":{"schemas":{"HairColor":{"type":"string","enum":["BLACK","BROWN","RED","BLOND","STBLOND","UNDEFINED"],"description":"UNDEFINED means unknown. Other codes are game categories, not DNA variants."},"PredictionRequest":{"type":"object","additionalProperties":false,"required":["family"],"properties":{"family":{"type":"object","additionalProperties":false,"description":"Omitted colors default to UNDEFINED; no parent or grandparent color is mandatory.","properties":{"mother":{"$ref":"#/components/schemas/HairColor","default":"UNDEFINED"},"father":{"$ref":"#/components/schemas/HairColor","default":"UNDEFINED"},"maternalGrandmother":{"$ref":"#/components/schemas/HairColor","default":"UNDEFINED"},"maternalGrandfather":{"$ref":"#/components/schemas/HairColor","default":"UNDEFINED"},"paternalGrandmother":{"$ref":"#/components/schemas/HairColor","default":"UNDEFINED"},"paternalGrandfather":{"$ref":"#/components/schemas/HairColor","default":"UNDEFINED"}}},"locale":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"],"default":"en","description":"Response labels and explanation language. Does not alter the calculation."}}},"ColorResult":{"type":"object","additionalProperties":false,"required":["color","label","percentage"],"properties":{"color":{"type":"string","enum":["BLACK","BROWN","RED","BLOND","STBLOND"]},"label":{"type":"string","minLength":1},"percentage":{"type":"number","minimum":0,"maximum":100}}},"PredictionResponse":{"oneOf":[{"type":"object","additionalProperties":false,"required":["apiVersion","modelVersion","purpose","scientificallyValidated","locale","unit","explanation","sourceUrl","documentationUrl","status","results"],"properties":{"apiVersion":{"type":"string","const":"1"},"modelVersion":{"type":"string","const":"hair-game-v1"},"purpose":{"type":"string","const":"entertainment"},"scientificallyValidated":{"type":"boolean","const":false},"locale":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]},"unit":{"type":"string","const":"percent"},"explanation":{"type":"string","minLength":1},"sourceUrl":{"type":"string","format":"uri"},"documentationUrl":{"type":"string","format":"uri"},"status":{"const":"ok"},"results":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"description":"One entry for each of the five known colors, including zero values. Percentages total 100 in the game.","items":{"$ref":"#/components/schemas/ColorResult"}}}},{"type":"object","additionalProperties":false,"required":["apiVersion","modelVersion","purpose","scientificallyValidated","locale","unit","explanation","sourceUrl","documentationUrl","status","results"],"properties":{"apiVersion":{"type":"string","const":"1"},"modelVersion":{"type":"string","const":"hair-game-v1"},"purpose":{"type":"string","const":"entertainment"},"scientificallyValidated":{"type":"boolean","const":false},"locale":{"type":"string","enum":["ar","de","en","es","fr","hi","ja","pt","ru","zh"]},"unit":{"type":"string","const":"percent"},"explanation":{"type":"string","minLength":1},"sourceUrl":{"type":"string","format":"uri"},"documentationUrl":{"type":"string","format":"uri"},"status":{"const":"needs_input"},"results":{"type":"null"}}}]},"ApiError":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["query_parameters_not_allowed","invalid_json","invalid_request","request_too_large","unsupported_media_type","method_not_allowed","internal_error"]},"message":{"type":"string","enum":["Send family colors in the JSON body, without URL query parameters.","Send a valid UTF-8 JSON object.","Provide a family object using the documented fields and uppercase color codes, and an optional supported locale. Additional fields are not accepted.","The JSON body must not exceed 1024 bytes.","Use Content-Type: application/json and an uncompressed UTF-8 body.","Use POST with a JSON body.","The calculation could not be completed."]}}}}}}}}