{"openapi":"3.1.1","info":{"title":"IZIOS Lab Diamond Calculator — Read-only API","version":"1.0.0","description":"Cached retail shopping context from active saleable lab-grown inventory. All prices are USD dollars. Not an appraisal, resale value, insurance value, or availability promise. Start with presets, request one summary per normalized selection, and fetch samples only when displaying cards. No bulk enumeration. This is an HTTP API description, not an MCP server."},"servers":[{"url":"https://izios.com/api/price-calculator"}],"externalDocs":{"description":"Interactive calculator and methodology","url":"https://izios.com/diamond-price-calculator"},"x-related-services":[{"name":"Diamond Scout MCP","url":"https://izios.com/api/mcp/diamond-scout","tool":"ask_diamond_scout","description":"Existing natural-language diamond search for richer criteria and explicit pairs. Scout access controls and limits apply; this calculator document does not grant access. MCP responses are no-store, unlike cached calculator summaries."}],"paths":{"/analytics/summary":{"get":{"operationId":"getLabDiamondPriceEstimate","summary":"Get a cached price estimate and comparable-inventory statistics","description":"Use data.filters as the effective query. data.updatedAt is the aggregate-generation timestamp, not a product update or an atomic inventory snapshot. Aggregate HTTP caching permits 300 seconds browser, 1800 seconds shared and 300 seconds stale-while-revalidate; origin caching may add age. Show timestamp. A successful zero inventoryCount means no exact matches; price zeros are empty aggregates, not free diamonds. Breakdowns relax their own dimension to compare alternatives.","parameters":[{"name":"category","in":"query","schema":{"type":"string","enum":["white","fancy"],"default":"white"}},{"name":"shape","in":"query","required":false,"style":"form","explode":false,"description":"Diamond shape. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["ROUND","PRINCESS","OVAL","CUSHION","EMERALD","PEAR","ASSCHER","MARQUISE","HEART","RADIANT"]}}},{"name":"color","in":"query","required":false,"style":"form","explode":false,"description":"White category only. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["D","E","F","G","H","I","J"]}}},{"name":"fancyColors","in":"query","required":false,"style":"form","explode":false,"description":"Fancy category only. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["YELLOW","PINK","BLUE","GREEN","ORANGE","BROWN","RED","BLACK"]}}},{"name":"fancyIntensities","in":"query","required":false,"style":"form","explode":false,"description":"Applied only with fancy category and exactly one fancy color. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["Faint","Very Light","Light","Fancy Light","Fancy","Fancy Intense","Fancy Vivid","Fancy Dark","Fancy Deep"]}}},{"name":"clarity","in":"query","required":false,"style":"form","explode":false,"description":"Report clarity grades; not a guarantee of eye cleanliness. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["FL","IF","VVS1","VVS2","VS1","VS2","SI1","SI2","SI3","I1","I2","I3"]}}},{"name":"minCarat","in":"query","description":"Carats, rounded to nearest 0.05. Omitted or out-of-range values do not constrain results. Send both bounds in ascending order.","schema":{"type":"number","minimum":0,"maximum":5}},{"name":"maxCarat","in":"query","description":"Carats, rounded to nearest 0.05. Omitted or out-of-range values do not constrain results. Send both bounds in ascending order.","schema":{"type":"number","minimum":0,"maximum":5}},{"name":"priceMin","in":"query","description":"USD dollars, rounded to nearest $100. Omitted or out-of-range values do not constrain results. Read normalized filters; this is not an exact-dollar search.","schema":{"type":"number","minimum":0,"maximum":9999}},{"name":"maxPrice","in":"query","description":"USD dollars, rounded to nearest $100. Omitted or out-of-range values do not constrain results. Read normalized filters; this is not an exact-dollar search.","schema":{"type":"number","minimum":0,"maximum":9999}}],"responses":{"200":{"description":"Cached aggregate; all monetary fields in USD.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Honor the actual response cache policy; errors are no-store."},"X-IZIOS-Price-Calculator-Cache":{"schema":{"type":"string","enum":["hit","miss","coalesced"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Summary"}},"required":["success","data"]}}}},"500":{"description":"Estimate unavailable. Do not interpret failure as zero matches.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Honor the actual response cache policy; errors are no-store."},"X-IZIOS-Price-Calculator-Cache":{"schema":{"type":"string","enum":["hit","miss","coalesced"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":false},"error":{"type":"string"}},"required":["success","error"]}}}},"503":{"description":"Shared fill capacity is busy. Honor Retry-After; use bounded exponential backoff with jitter, then stop.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Honor the actual response cache policy; errors are no-store."},"X-IZIOS-Price-Calculator-Cache":{"schema":{"type":"string","enum":["hit","miss","coalesced"]}},"Retry-After":{"schema":{"type":"string"},"description":"Delay in seconds."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":false},"error":{"type":"string"}},"required":["success","error"]}}}}}}},"/analytics/presets":{"get":{"operationId":"getLabDiamondCalculatorPresets","summary":"Start with bounded common shopping selections","responses":{"200":{"description":"Cached preset estimates. No per-preset generation timestamp is returned.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Honor the actual response cache policy; errors are no-store."},"X-IZIOS-Price-Calculator-Cache":{"schema":{"type":"string","enum":["hit","miss","coalesced"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"presets":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}}},"required":["success","presets"]}}}},"500":{"description":"Estimate unavailable. Do not interpret failure as zero matches.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Honor the actual response cache policy; errors are no-store."},"X-IZIOS-Price-Calculator-Cache":{"schema":{"type":"string","enum":["hit","miss","coalesced"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":false},"error":{"type":"string"}},"required":["success","error"]}}}},"503":{"description":"Shared fill capacity is busy. Honor Retry-After; use bounded exponential backoff with jitter, then stop.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Honor the actual response cache policy; errors are no-store."},"X-IZIOS-Price-Calculator-Cache":{"schema":{"type":"string","enum":["hit","miss","coalesced"]}},"Retry-After":{"schema":{"type":"string"},"description":"Delay in seconds."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":false},"error":{"type":"string"}},"required":["success","error"]}}}}}}},"/analytics/samples":{"get":{"operationId":"getLabDiamondExampleCards","summary":"Get up to six example cards for a selection","description":"At most two examples per low/medium/high tier; tiers can overlap. Deduplicate by id. Not pagination or an exhaustive search. Media preference influences selection. Cache-Control is private, max-age=30, must-revalidate: do not put product responses in a shared cache. Product pages are the final availability source; do not infer missing grades, media or scores. Retail prices and carats may be JSON numbers or numeric strings.","parameters":[{"name":"category","in":"query","schema":{"type":"string","enum":["white","fancy"],"default":"white"}},{"name":"shape","in":"query","required":false,"style":"form","explode":false,"description":"Diamond shape. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["ROUND","PRINCESS","OVAL","CUSHION","EMERALD","PEAR","ASSCHER","MARQUISE","HEART","RADIANT"]}}},{"name":"color","in":"query","required":false,"style":"form","explode":false,"description":"White category only. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["D","E","F","G","H","I","J"]}}},{"name":"fancyColors","in":"query","required":false,"style":"form","explode":false,"description":"Fancy category only. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["YELLOW","PINK","BLUE","GREEN","ORANGE","BROWN","RED","BLACK"]}}},{"name":"fancyIntensities","in":"query","required":false,"style":"form","explode":false,"description":"Applied only with fancy category and exactly one fancy color. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["Faint","Very Light","Light","Fancy Light","Fancy","Fancy Intense","Fancy Vivid","Fancy Dark","Fancy Deep"]}}},{"name":"clarity","in":"query","required":false,"style":"form","explode":false,"description":"Report clarity grades; not a guarantee of eye cleanliness. Comma-separated; case normalized, duplicates removed. Unknown values are discarded. Inspect returned filters.","schema":{"type":"array","maxItems":12,"items":{"type":"string","enum":["FL","IF","VVS1","VVS2","VS1","VS2","SI1","SI2","SI3","I1","I2","I3"]}}},{"name":"minCarat","in":"query","description":"Carats, rounded to nearest 0.05. Omitted or out-of-range values do not constrain results. Send both bounds in ascending order.","schema":{"type":"number","minimum":0,"maximum":5}},{"name":"maxCarat","in":"query","description":"Carats, rounded to nearest 0.05. Omitted or out-of-range values do not constrain results. Send both bounds in ascending order.","schema":{"type":"number","minimum":0,"maximum":5}},{"name":"priceMin","in":"query","description":"USD dollars, rounded to nearest $100. Omitted or out-of-range values do not constrain results. Read normalized filters; this is not an exact-dollar search.","schema":{"type":"number","minimum":0,"maximum":9999}},{"name":"maxPrice","in":"query","description":"USD dollars, rounded to nearest $100. Omitted or out-of-range values do not constrain results. Read normalized filters; this is not an exact-dollar search.","schema":{"type":"number","minimum":0,"maximum":9999}}],"responses":{"200":{"description":"Public card fields only; no availability reservation.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Honor the actual response cache policy; errors are no-store."},"X-IZIOS-Price-Calculator-Cache":{"schema":{"type":"string","enum":["hit","miss","coalesced"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"samples":{"type":"object","properties":{"low":{"type":"array","items":{"$ref":"#/components/schemas/Sample"},"maxItems":2},"medium":{"type":"array","items":{"$ref":"#/components/schemas/Sample"},"maxItems":2},"high":{"type":"array","items":{"$ref":"#/components/schemas/Sample"},"maxItems":2}},"required":["low","medium","high"]}},"required":["success","samples"]}}}},"500":{"description":"Estimate unavailable. Do not interpret failure as zero matches.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Honor the actual response cache policy; errors are no-store."},"X-IZIOS-Price-Calculator-Cache":{"schema":{"type":"string","enum":["hit","miss","coalesced"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":false},"error":{"type":"string"}},"required":["success","error"]}}}},"503":{"description":"Shared fill capacity is busy. Honor Retry-After; use bounded exponential backoff with jitter, then stop.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Honor the actual response cache policy; errors are no-store."},"X-IZIOS-Price-Calculator-Cache":{"schema":{"type":"string","enum":["hit","miss","coalesced"]}},"Retry-After":{"schema":{"type":"string"},"description":"Delay in seconds."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":false},"error":{"type":"string"}},"required":["success","error"]}}}}}}}},"components":{"schemas":{"Filters":{"type":"object","properties":{"category":{"type":"string","enum":["white","fancy"]},"shape":{"type":"array","items":{"type":"string"}},"color":{"type":"array","items":{"type":"string"}},"fancyColors":{"type":"array","items":{"type":"string"}},"fancyIntensities":{"type":"array","items":{"type":"string"}},"clarity":{"type":"array","items":{"type":"string"}},"minCarat":{"type":["number","null"]},"maxCarat":{"type":["number","null"]},"priceMin":{"type":["number","null"]},"maxPrice":{"type":["number","null"]}},"required":["category","shape","color","fancyColors","fancyIntensities","clarity","minCarat","maxCarat","priceMin","maxPrice"]},"Summary":{"type":"object","properties":{"filters":{"$ref":"#/components/schemas/Filters"},"inventoryCount":{"type":"integer","minimum":0},"unboundedInventoryCount":{"type":"integer","minimum":0},"budgetCoveragePct":{"type":"number"},"price":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"p25":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"median":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"p75":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"max":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"average":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."}},"required":["min","p25","median","p75","max","average"],"description":"Comparable price statistics before the maximum budget ceiling. inventoryCount applies maxPrice; these market prices may exceed it."},"distribution":{"type":"array","items":{"type":"object","properties":{"minPrice":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"maxPrice":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"averagePrice":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"count":{"type":"integer","minimum":0}},"required":["minPrice","maxPrice","averagePrice","count"]}},"breakdowns":{"type":"object","properties":{"byShape":{"type":"array","items":{"$ref":"#/components/schemas/Breakdown"}},"byColor":{"type":"array","items":{"$ref":"#/components/schemas/Breakdown"}},"byClarity":{"type":"array","items":{"$ref":"#/components/schemas/Breakdown"}}},"required":["byShape","byColor","byClarity"]},"coverage":{"type":"object","properties":{"mediaReadyCount":{"type":"integer","minimum":0},"certifiedCount":{"type":"integer","minimum":0},"certificateLabCount":{"type":"integer","minimum":0},"lightScoreCount":{"type":"integer","minimum":0},"valueScoreCount":{"type":"integer","minimum":0},"mediaReadyPct":{"type":"number"},"certifiedPct":{"type":"number"},"lightScorePct":{"type":"number"},"valueScorePct":{"type":"number"}},"required":["mediaReadyCount","certifiedCount","certificateLabCount","lightScoreCount","valueScoreCount","mediaReadyPct","certifiedPct","lightScorePct","valueScorePct"]},"facts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"}},"required":["id","title","body"]}},"updatedAt":{"type":"string","format":"date-time"}},"required":["filters","inventoryCount","unboundedInventoryCount","budgetCoveragePct","price","distribution","breakdowns","coverage","facts","updatedAt"]},"Breakdown":{"type":"object","properties":{"label":{"type":"string"},"count":{"type":"integer","minimum":0},"minPrice":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"medianPrice":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"maxPrice":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"averagePrice":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"deltaPct":{"type":"number"},"selected":{"type":"boolean"}},"required":["label","count","minPrice","medianPrice","maxPrice","averagePrice","deltaPct","selected"]},"Preset":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"filters":{"$ref":"#/components/schemas/Filters"},"count":{"type":"integer","minimum":0},"medianPrice":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"p25Price":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."},"p75Price":{"type":"number","minimum":0,"description":"Retail price in USD dollars, not cents."}},"required":["id","title","detail","filters","count","medianPrice","p25Price","p75Price"]},"Sample":{"type":"object","required":["id","retailPrice"],"properties":{"id":{"type":["string","integer"]},"carat":{"type":["number","string","null"]},"retailPrice":{"type":["number","string","null"]},"lightScore":{"type":["number","string","null"]},"valueScore":{"type":["number","string","null"]},"lengthMm":{"type":["number","string","null"],"description":"Reported face-up dimension in millimeters. Normalize longest / shortest for L/W; missing dimensions do not imply 1:1."},"widthMm":{"type":["number","string","null"],"description":"Reported face-up dimension in millimeters. Normalize longest / shortest for L/W; missing dimensions do not imply 1:1."},"stockId":{"type":["string","null"]},"seoUrl":{"type":["string","null"]},"shape":{"type":["string","null"]},"color":{"type":["string","null"]},"fancyColor":{"type":["string","null"]},"fancyIntensity":{"type":["string","null"]},"clarity":{"type":["string","null"]},"cut":{"type":["string","null"]},"certificateLab":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"videoUrl":{"type":["string","null"]},"v360Url":{"type":["string","null"]}}}}}}