{ "openapi": "3.1.0", "info": { "title": "Brilliant Colors public inventory", "version": "1.0.0", "description": "Read-only public inventory. No credentials or private prices. Connect explicitly in a supported client; publishing this file does not register with chatbots. Recheck detail before relying on availability." }, "servers": [ { "url": "https://www.brilliantcolorsinc.com", "description": "Public HTTPS inventory service; read-only GET requests without credentials." } ], "paths": { "/inventory-api.php": { "get": { "operationId": "searchOrGetGemstones", "summary": "Search current public gemstones or get a SKU", "parameters": [ { "name": "sku", "in": "query", "required": false, "description": "Detail lookup; cannot be combined with search parameters.", "schema": { "type": "string", "maxLength": 64 } }, { "name": "type", "in": "query", "required": false, "description": "Catalog code or label, e.g. SA or Sapphire. Sapphire includes Padparadscha. Padparadscha remains an exact classification search.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "color", "in": "query", "required": false, "description": "Catalog code or label, e.g. YL or Yellow. With type=Sapphire, Peach includes peach sapphires and all Padparadscha records. Other types retain ordinary color matching.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "shapes", "in": "query", "required": false, "description": "Comma-separated alternative cuts; codes or labels, e.g. EC,AS or Emerald Cut,Asscher. At most ten.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "origin", "in": "query", "required": false, "description": "Optional exact recorded origin text; absent values do not match. Never infer from description.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "treatment", "in": "query", "required": false, "description": "Code or label: H Heated, N Untreated, O Oiling/Resin, BE Beryllium, D Diffusion.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "laboratory", "in": "query", "required": false, "description": "Exact lab name/code; Lotus and Gubelin aliases supported.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "min_carat", "in": "query", "required": false, "description": "Inclusive listing carats; combined weight for pairs. Positive wt otherwise positive mwt.", "schema": { "type": "number", "minimum": 0, "maximum": 100000 } }, { "name": "max_carat", "in": "query", "required": false, "description": "Inclusive listing carats; combined weight for pairs. Positive wt otherwise positive mwt.", "schema": { "type": "number", "minimum": 0, "maximum": 100000 } }, { "name": "min_length_mm", "in": "query", "required": false, "description": "Inclusive longer recorded face-up axis in MM; rotation allowed. Both dimensions must be positive. Dimensional match only, not guaranteed mounting fit.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 } }, { "name": "max_length_mm", "in": "query", "required": false, "description": "Inclusive longer recorded face-up axis in MM; rotation allowed. Both dimensions must be positive. Dimensional match only, not guaranteed mounting fit.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 } }, { "name": "min_width_mm", "in": "query", "required": false, "description": "Inclusive shorter recorded face-up axis in MM; rotation allowed. Both dimensions must be positive. Dimensional match only, not guaranteed mounting fit.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 } }, { "name": "max_width_mm", "in": "query", "required": false, "description": "Inclusive shorter recorded face-up axis in MM; rotation allowed. Both dimensions must be positive. Dimensional match only, not guaranteed mounting fit.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 } }, { "name": "availability", "in": "query", "required": false, "description": "Search availability. Defaults to available; unavailable includes eligible records not currently available, including memo stock, and does not prove a sale. all includes both. Recheck the selected SKU before relying on availability.", "schema": { "type": "string", "enum": [ "available", "unavailable", "all" ], "default": "available" } }, { "name": "matching", "in": "query", "required": false, "description": "single selects individual stones; pair selects matching pairs; all includes both and is the default when omitted. Pair carat weight is combined, not per stone.", "schema": { "type": "string", "enum": [ "pair", "single", "all" ], "default": "all" } }, { "name": "sort", "in": "query", "required": false, "description": "Ordering only; does not relax any filter. Defaults to carat_asc. Public price sorting is not supported.", "schema": { "type": "string", "enum": [ "carat_asc", "carat_desc", "length_asc", "length_desc", "width_asc", "width_desc", "sku", "sku_asc", "sku_desc" ], "default": "carat_asc" } }, { "name": "certification", "in": "query", "required": false, "description": "Filter by laboratory metadata: recorded means a laboratory is recorded; unknown means none is recorded and is displayed as Not Certified under Brilliant Colors' catalog business convention. This does not independently verify certification. A missing certificate file does not remove a recorded laboratory: documents may be awaiting delivery and scanning.", "schema": { "type": "string", "enum": [ "recorded", "unknown" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results per page: default 20, maximum 50. Use has_more and next_offset to retrieve remaining matches; pagination can shift across inventory updates.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based result offset; default 0. For the next page use the returned next_offset with all other search filters unchanged. Recheck selected detail because inventory can change.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "min_price", "in": "query", "required": false, "description": "Reserved; anonymous requests always receive 403. No public pricing or price sorting.", "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "required": false, "description": "Reserved; anonymous requests always receive 403. No public pricing or price sorting.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Search or detail; JSON and private/no-store. Search may be empty.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "checked_at", "filters", "items", "has_more", "next_offset" ], "properties": { "checked_at": { "type": "string", "format": "date-time", "description": "Query time, not sync time." }, "filters": { "type": "object" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Gemstone" } }, "has_more": { "type": "boolean", "description": "True when more results remain for this search. Fetch next_offset before claiming a complete result set." }, "next_offset": { "type": [ "integer", "null" ], "description": "Offset to use in the next otherwise identical search; null when no further results remain." } } }, { "type": "object", "required": [ "checked_at", "item" ], "properties": { "checked_at": { "type": "string", "format": "date-time" }, "item": { "$ref": "#/components/schemas/Gemstone" } } } ] } } } }, "400": { "description": "Invalid filters or unknown parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Anonymous pricing restricted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Missing or nonpublic SKU", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "405": { "description": "Only GET supported", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Request limit exceeded; retry after the indicated seconds", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Inventory or rate storage unavailable; do not interpret as empty inventory", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Search combines supplied filters: each result must satisfy every filter. Comma-separated shapes are alternatives within the shape filter. Do not silently relax weight, dimensions, treatment or availability; label any separately requested relaxed search as alternatives. HTTP 200 with items=[] means no exact matches at query time; an HTTP error is not an empty inventory result.\n\nWorked example: available single blue sapphires, oval OR cushion, no heat (treatment=N), 2.99–4.00 ct, longer face-up axis 10–11 mm and shorter axis 8–9 mm. All bounds are inclusive. Both shapes use the same dimension bounds in this example. If a customer intends different bounds for cushions, clarify that before applying them.\n\nGET https://www.brilliantcolorsinc.com/inventory-api.php?type=SA&color=BL&shapes=OV,CU&treatment=N&matching=single&min_carat=2.99&max_carat=4&min_length_mm=10&max_length_mm=11&min_width_mm=8&max_width_mm=9&availability=available&sort=carat_asc&limit=1&offset=0\n\nThe example deliberately uses limit=1 to demonstrate pagination. Read items, has_more and next_offset. When has_more is true, repeat the same search with offset set to the returned next_offset, keeping every other filter unchanged. Continue until has_more is false; do not infer completeness from the first page. Use limit=50 for fewer requests. Inventory may change between requests; deduplicate by sku and recheck selected details.\n\nDetail example: GET https://www.brilliantcolorsinc.com/inventory-api.php?sku=7144 . Detail accepts sku alone and returns {checked_at,item}, whereas search returns {checked_at,filters,items,has_more,next_offset}. Example SKUs are illustrative and may later become unavailable or return 404. Use each returned item's url as its direct listing link, not the general catalog URL. Recheck item.availability before presenting it as available; checked_at is query time, not inventory synchronization time.\n\nUse certification.label for the website wording (Not Certified or recorded laboratory names). certification.status describes laboratory records, not the existence of a scanned certificate. Missing document media does not erase a recorded laboratory. Public prices are hidden; never invent a price or treat price upon request as a numeric price. On 429 or 503 respect Retry-After; report temporary failure rather than no matches." } } }, "components": { "schemas": { "Gemstone": { "type": "object", "additionalProperties": false, "properties": { "sku": { "type": "string" }, "description": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "shape": { "type": [ "string", "null" ] }, "carat_weight": { "type": [ "number", "null" ] }, "is_pair": { "type": "boolean" }, "weight_basis": { "enum": [ "combined_pair", "listing" ] }, "dimensions_mm": { "type": "object", "properties": { "length": { "type": [ "number", "null" ] }, "width": { "type": [ "number", "null" ] }, "depth": { "type": [ "number", "null" ] } }, "description": "Recorded listing dimensions; depth unverified and null." }, "origin": { "type": [ "string", "null" ] }, "treatment": { "type": [ "string", "null" ] }, "certification": { "description": "Laboratory record status, separate from certificate-file availability. The website displays Not Certified when no laboratory is recorded (status unknown, laboratories []). This is a catalog business convention, not independent proof that no certificate exists. A recorded laboratory remains recorded while its certificate document is awaiting delivery, scanning or linking to the SKU.", "type": "object", "properties": { "label": { "type": "string", "description": "Shared website display label: Not Certified when no laboratory is recorded; otherwise distinct normalized laboratory names separated by comma and space, with no trailing comma. A single laboratory has no comma. Independent of certificate-file availability.", "examples": [ "Not Certified", "GIA", "GIA, Lotus" ] }, "status": { "enum": [ "recorded", "unknown" ] }, "laboratories": { "type": "array", "items": { "type": "string" } }, "independently_verified": { "const": false } } }, "availability": { "enum": [ "available", "unavailable" ] }, "image": { "type": [ "object", "null" ], "properties": { "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" } } }, "url": { "type": "string", "format": "uri", "description": "Direct public gemstone listing URL. Use this returned URL when linking the specific result." }, "pricing_visibility": { "const": "hidden" }, "inventory_status": { "type": "string", "enum": [ "available", "on_memo", "unavailable", "inactive" ], "description": "Inventory status: on_memo means zero shelf quantity and positive memo quantity. Unavailable does not establish that a stone was sold." } }, "required": [ "sku", "description", "type", "color", "shape", "carat_weight", "is_pair", "weight_basis", "dimensions_mm", "origin", "treatment", "certification", "availability", "image", "url", "pricing_visibility" ] } } } }