Using the inventory API

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.

Search workflow

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.

Worked 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.

Example request HTTP GET

GET 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

The 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.

Detail 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.

Use 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.

Parameters

Supply query parameters to /inventory-api.php. A detail lookup uses sku alone.

Inventory request parameters
Parameter	Meaning and limits
sku	Detail lookup; cannot be combined with search parameters. Maximum characters: 64
type	Catalog code or label, e.g. SA or Sapphire. Sapphire includes Padparadscha. Padparadscha remains an exact classification search. Maximum characters: 200
color	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. Maximum characters: 200
shapes	Comma-separated alternative cuts; codes or labels, e.g. EC,AS or Emerald Cut,Asscher. At most ten. Maximum characters: 200
origin	Optional exact recorded origin text; absent values do not match. Never infer from description. Maximum characters: 200
treatment	Code or label: H Heated, N Untreated, O Oiling/Resin, BE Beryllium, D Diffusion. Maximum characters: 200
laboratory	Exact lab name/code; Lotus and Gubelin aliases supported. Maximum characters: 200
min_carat	Inclusive listing carats; combined weight for pairs. Positive wt otherwise positive mwt. Minimum: 0. Maximum: 100000
max_carat	Inclusive listing carats; combined weight for pairs. Positive wt otherwise positive mwt. Minimum: 0. Maximum: 100000
min_length_mm	Inclusive longer recorded face-up axis in MM; rotation allowed. Both dimensions must be positive. Dimensional match only, not guaranteed mounting fit. Greater than: 0. Maximum: 1000
max_length_mm	Inclusive longer recorded face-up axis in MM; rotation allowed. Both dimensions must be positive. Dimensional match only, not guaranteed mounting fit. Greater than: 0. Maximum: 1000
min_width_mm	Inclusive shorter recorded face-up axis in MM; rotation allowed. Both dimensions must be positive. Dimensional match only, not guaranteed mounting fit. Greater than: 0. Maximum: 1000
max_width_mm	Inclusive shorter recorded face-up axis in MM; rotation allowed. Both dimensions must be positive. Dimensional match only, not guaranteed mounting fit. Greater than: 0. Maximum: 1000
availability	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. Values: available, unavailable, all. Default: available
matching	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. Values: pair, single, all. Default: all
sort	Ordering only; does not relax any filter. Defaults to carat_asc. Public price sorting is not supported. Values: carat_asc, carat_desc, length_asc, length_desc, width_asc, width_desc, sku, sku_asc, sku_desc. Default: carat_asc
certification	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. Values: recorded, unknown
limit	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. Default: 20. Minimum: 1. Maximum: 50
offset	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. Default: 0. Minimum: 0. Maximum: 10000
min_price	Reserved; anonymous requests always receive 403. No public pricing or price sorting.
max_price	Reserved; anonymous requests always receive 403. No public pricing or price sorting.

Response status

HTTP response statuses
Status	Meaning
200	Search or detail; JSON and private/no-store. Search may be empty.
400	Invalid filters or unknown parameters
403	Anonymous pricing restricted
404	Missing or nonpublic SKU
405	Only GET supported
429	Request limit exceeded; retry after the indicated seconds
503	Inventory or rate storage unavailable; do not interpret as empty inventory

Laboratories and certificate documents

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.