Ministry of Gems — Gemmology & Gemstones

Look up a gemmological term in The Gem Lexicon of Ministry of Gems — 215 definitions verified by an FGAA-qualified gemmologist. Returns the definition, its subject section, and a citable anchor URL. Use for terms such as padparadscha, corundum, parti sapphire, unheated, or asterism.

{
  "type": "object",
  "properties": {
    "term": {
      "type": "string",
      "description": "The gemmological term to define."
    }
  },
  "required": [
    "term"
  ]
}

{
  "type": "object",
  "properties": {
    "term": {
      "type": "string",
      "description": "Canonical term name."
    },
    "definition": {
      "type": "string",
      "description": "FGAA-verified definition."
    },
    "section": {
      "type": "string",
      "description": "Lexicon subject section."
    },
    "url": {
      "type": "string",
      "description": "Citable anchor URL on ministryofgems.com.au."
    },
    "verified_by": {
      "type": "string",
      "description": "Credential of the verifying gemmologist."
    },
    "source": {
      "type": "string",
      "description": "Name of the source work."
    },
    "found": {
      "type": "boolean",
      "description": "False when no term matched."
    },
    "message": {
      "type": "string"
    },
    "hint": {
      "type": "string"
    },
    "lexicon_url": {
      "type": "string"
    }
  },
  "description": "The verified definition, or found:false with a hint when no term matches."
}

Keyword search across the Ministry of Gems gemmological reference library — 215 lexicon definitions and 25 full-length buyer's handbooks, searched in full text across every section. Returns ranked results, each with the matched passage and a citable URL that deep-links to the chapter.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query."
    },
    "limit": {
      "type": "integer",
      "description": "Max results (default 5, max 20)."
    }
  },
  "required": [
    "query"
  ]
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The query as interpreted."
    },
    "result_count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "description": "Ranked matches.",
      "items": {
        "type": "object",
        "properties": {
          "score": {
            "type": "number",
            "description": "Relevance score. Not emitted; ordering conveys rank."
          },
          "type": {
            "type": "string",
            "description": "lexicon_term, handbook_section or handbook."
          },
          "title": {
            "type": "string",
            "description": "Lexicon term name, or the handbook title."
          },
          "section": {
            "type": "string",
            "description": "Lexicon subject section, or the handbook section heading."
          },
          "snippet": {
            "type": "string",
            "description": "Verbatim passage from the published text, centred on the match."
          },
          "url": {
            "type": "string",
            "description": "Citable URL, deep-linked to the chapter where possible."
          }
        }
      }
    },
    "verified_by": {
      "type": "string"
    }
  },
  "required": [
    "query",
    "result_count",
    "results"
  ]
}

List the gemmological terms available in The Gem Lexicon, optionally filtered to one subject section. Use this to discover what can be defined before calling define_gem_term.

{
  "type": "object",
  "properties": {
    "section": {
      "type": "string",
      "description": "Optional section filter, e.g. \"Treatments & Enhancement\"."
    }
  }
}

{
  "type": "object",
  "properties": {
    "sections": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "All lexicon section names."
    },
    "term_count": {
      "type": "integer"
    },
    "terms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "term": {
            "type": "string"
          },
          "section": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "sections",
    "term_count",
    "terms"
  ]
}

Cryptographically verify a Ministry of Gems Digital Gemstone Passport by stone ID. Recomputes the SHA-256 digest of the signed record and checks its Ed25519 (EdDSA) signature against the house public key, then returns the attested record: species, carat, dimensions, cut, colour, clarity, origin, treatment and certificate status. Use when a buyer asks whether a stone or its passport is genuine, or before quoting any fact about a specific Ministry of Gems stone.

{
  "type": "object",
  "properties": {
    "stone_id": {
      "type": "string",
      "description": "Stone ID as printed on the passport or product page, e.g. \"12322\", \"RUBY-B0797\", \"80067\"."
    }
  },
  "required": [
    "stone_id"
  ]
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "verified": {
      "type": "boolean",
      "description": "True only when digest and signature both check out."
    },
    "stone_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "product_url": {
      "type": "string"
    },
    "fingerprint": {
      "type": "string"
    },
    "sha256": {
      "type": "string"
    },
    "digest_matches": {
      "type": "boolean"
    },
    "signature_valid": {
      "type": "boolean"
    },
    "issued": {
      "type": "string"
    },
    "record": {
      "type": "object"
    },
    "corpus_url": {
      "type": "string"
    },
    "register_url": {
      "type": "string"
    },
    "note": {
      "type": "string"
    }
  }
}

Search the live Ministry of Gems catalogue of natural loose gemstones and finished jewellery — Ceylon and Australian sapphires, rubies, spinels, Australian opals, emeralds and more — with prices in Australian dollars, availability, carat weight and a link to buy. Filter by type (gems, ring, pendant, earrings), carat range and price range. Every loose gem returned carries a verifiable Digital Gemstone Passport.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free text, e.g. \"unheated ceylon blue sapphire\", \"australian opal pendant\", \"teal sapphire ring\"."
    },
    "type": {
      "type": "string",
      "description": "Optional: gems | ring | pendant | earrings | bracelet | jewellery."
    },
    "min_carat": {
      "type": "number"
    },
    "max_carat": {
      "type": "number"
    },
    "min_price_aud": {
      "type": "number"
    },
    "max_price_aud": {
      "type": "number"
    },
    "in_stock_only": {
      "type": "boolean",
      "description": "Default true."
    },
    "limit": {
      "type": "integer",
      "description": "Max results, default 8, max 25."
    }
  }
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "result_count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "price_aud": {
            "type": "number"
          },
          "available": {
            "type": "boolean"
          },
          "carat": {
            "type": "number"
          },
          "product_type": {
            "type": "string"
          },
          "passport_url": {
            "type": "string"
          },
          "stone_id": {
            "type": "string"
          },
          "image": {
            "type": "string"
          }
        }
      }
    },
    "currency": {
      "type": "string"
    },
    "catalogue_size": {
      "type": "integer"
    }
  },
  "required": [
    "query",
    "result_count",
    "results"
  ]
}

What natural sapphires actually cost per carat in Australian dollars, from Ministry of Gems' published price guide: bands by origin (Australian, Ceylon) and size, with the stone count behind each band and the date the bands were computed. Answers "how much is a 2 carat sapphire" honestly, as a house guide rather than a market index.

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "description": "Optional: \"Australian\" or \"Ceylon\"."
    },
    "carat": {
      "type": "number",
      "description": "Optional carat weight to select the matching band."
    }
  }
}

{
  "type": "object",
  "properties": {
    "as_of": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "matched_bands": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "all_bands": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "source_url": {
      "type": "string"
    },
    "basis": {
      "type": "string"
    },
    "note": {
      "type": "string"
    }
  }
}

Mohs hardness, refractive index, specific gravity, birefringence and crystal system for a gem species (diamond, corundum/sapphire/ruby, emerald, spinel, opal, tourmaline, garnet, quartz and more), from the FGAA-reviewed Gem Data Tables. Accepts trade names — "sapphire" resolves to corundum, "tsavorite" to garnet.

{
  "type": "object",
  "properties": {
    "species": {
      "type": "string",
      "description": "Species or trade name, e.g. \"sapphire\", \"diamond\", \"opal\"."
    }
  },
  "required": [
    "species"
  ]
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "species": {
      "type": "string"
    },
    "mohs_hardness": {
      "type": "string"
    },
    "refractive_index": {
      "type": "string"
    },
    "specific_gravity": {
      "type": "string"
    },
    "birefringence": {
      "type": "string"
    },
    "crystal_system": {
      "type": "string"
    },
    "source_url": {
      "type": "string"
    },
    "licence": {
      "type": "string"
    }
  }
}

Side-by-side physical properties of two gem species with a plain verdict on which is harder, and a note on toughness — the half of durability the hardness scale does not show. Good for "sapphire or diamond for an everyday ring".

{
  "type": "object",
  "properties": {
    "gem_a": {
      "type": "string"
    },
    "gem_b": {
      "type": "string"
    }
  },
  "required": [
    "gem_a",
    "gem_b"
  ]
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "a": {
      "type": "object"
    },
    "b": {
      "type": "object"
    },
    "harder": {
      "type": "string"
    },
    "note": {
      "type": "string"
    }
  }
}

The modern and traditional birthstones for a month, from the FGAA-reviewed table, with a link to The Birthstone Handbook for history, treatments to expect and buying guidance. Accepts a month name or number.

{
  "type": "object",
  "properties": {
    "month": {
      "type": "string",
      "description": "\"September\", \"sep\" or \"9\"."
    }
  },
  "required": [
    "month"
  ]
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "month": {
      "type": "string"
    },
    "modern": {
      "type": "string"
    },
    "traditional_or_alternative": {
      "type": "string"
    },
    "handbook_url": {
      "type": "string"
    },
    "source_url": {
      "type": "string"
    }
  }
}

Whether warm soapy water, an ultrasonic cleaner or a steam cleaner is safe for a given gemstone, plus everyday-wear notes, from the FGAA-reviewed care table. Covers sapphire and ruby, diamond, emerald, opal, pearl, tanzanite, tourmaline and more.

{
  "type": "object",
  "properties": {
    "gemstone": {
      "type": "string"
    }
  },
  "required": [
    "gemstone"
  ]
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "gemstone": {
      "type": "string"
    },
    "warm_soapy_water": {
      "type": "string"
    },
    "ultrasonic_cleaner": {
      "type": "string"
    },
    "steam_cleaner": {
      "type": "string"
    },
    "everyday_wear_notes": {
      "type": "string"
    },
    "handbook_url": {
      "type": "string"
    },
    "source_url": {
      "type": "string"
    }
  }
}

Full detail for one Ministry of Gems product by handle or URL: specifications, description, price in AUD, availability, variants, images, the Digital Gemstone Passport link for loose stones, and a direct checkout link. Use after search_gem_inventory.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "Product handle (e.g. \"blue-australian-sapphire-1-47ct-oval-80062\") or full product URL."
    }
  },
  "required": [
    "handle"
  ]
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "title": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "price_aud": {
      "type": "number"
    },
    "available": {
      "type": "boolean"
    },
    "specifications": {
      "type": "object"
    },
    "description": {
      "type": "string"
    },
    "images": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "variants": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "passport_url": {
      "type": "string"
    },
    "stone_id": {
      "type": "string"
    },
    "checkout_link": {
      "type": "string"
    },
    "checked_at": {
      "type": "string"
    }
  }
}

The issuing laboratory's own verification page and a four-step checklist for confirming a gemstone or diamond grading report — GIA, IGI, GRS, SSEF, Gübelin, AGL, Lotus, GIT, HRD, GCAL and others, including the coloured-stone laboratories diamond tools omit. Explains what "FGAA" means and flags unrecognised lab names. Routes to the lab; does not verify the report itself.

{
  "type": "object",
  "properties": {
    "lab": {
      "type": "string",
      "description": "Laboratory name or acronym, e.g. \"GIA\", \"GRS\", \"SSEF\"."
    },
    "report_number": {
      "type": "string"
    }
  },
  "required": [
    "lab"
  ]
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "lab": {
      "type": "string"
    },
    "report_number": {
      "type": "string"
    },
    "verify_url": {
      "type": "string"
    },
    "verifies_coloured_stones": {
      "type": "boolean"
    },
    "checklist": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "lab_note": {
      "type": "string"
    },
    "house_position": {
      "type": "string"
    },
    "reminder": {
      "type": "string"
    }
  }
}

Approximate face-up millimetre dimensions for a stone of a given species, shape and carat weight — and, unlike diamond-only calculators, corrected for specific gravity, so a 2 ct sapphire, spinel, emerald or opal is sized correctly rather than as if it were diamond. Shapes: round, oval, cushion, emerald, pear, marquise, princess, radiant, heart, trillion.

{
  "type": "object",
  "properties": {
    "species": {
      "type": "string",
      "description": "e.g. sapphire, diamond, spinel, emerald, opal (default diamond)."
    },
    "shape": {
      "type": "string",
      "description": "default round"
    },
    "carat": {
      "type": "number"
    }
  },
  "required": [
    "carat"
  ]
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "species": {
      "type": "string"
    },
    "shape": {
      "type": "string"
    },
    "carat": {
      "type": "number"
    },
    "specific_gravity": {
      "type": "number"
    },
    "approx_face_up_mm": {
      "type": "object"
    },
    "display": {
      "type": "string"
    },
    "diamond_equivalent_mm": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "note": {
      "type": "string"
    }
  }
}