{
 "openapi": "3.1.0",
 "info": {
  "title": "Digital Gemology cut library API",
  "version": "1.1.0",
  "description": "Read-only, free, no key. Search 45 gem cuts and Platonic solids, their measured specifications, brilliance, fire and scintillation in 26 gemstones, prices and checkout links. The same data is served to AI agents by the MCP server at https://digitalgemology.com/mcp. Documentation: https://digitalgemology.com/about/agents.",
  "contact": {
   "name": "Digital Gemology",
   "email": "support@digitalgemology.com",
   "url": "https://digitalgemology.com/contact"
  },
  "termsOfService": "https://digitalgemology.com/terms",
  "license": {
   "name": "CC BY 4.0",
   "identifier": "CC-BY-4.0"
  }
 },
 "servers": [
  {
   "url": "https://digitalgemology.com"
  }
 ],
 "security": [],
 "externalDocs": {
  "url": "https://digitalgemology.com/about/agents"
 },
 "paths": {
  "/api/cuts": {
   "get": {
    "operationId": "searchCuts",
    "summary": "Search the cut library",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Free text. Leave it out to list every cut that fits the filters."
     },
     {
      "name": "category",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "brilliants",
        "jewelry",
        "historic",
        "house",
        "platonic"
       ]
      },
      "description": "brilliants, jewelry (fancy and step cuts), historic, house (our own designs) or platonic (solids, 3D files only)."
     },
     {
      "name": "shape",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "round",
        "elongated",
        "square",
        "triangular",
        "other",
        "solid"
       ]
      },
      "description": "Outline of the cut."
     },
     {
      "name": "gemstone",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "diamond",
        "moissanite",
        "cubic-zirconia",
        "ruby",
        "sapphire",
        "emerald",
        "amethyst",
        "topaz",
        "spinel",
        "demantoid",
        "zircon",
        "tourmaline",
        "peridot",
        "tanzanite",
        "yag",
        "pyrope",
        "almandine",
        "spessartine",
        "grossular",
        "chrysoberyl",
        "kunzite",
        "iolite",
        "morganite",
        "ggg",
        "strontium-titanate",
        "synthetic-rutile",
        "aquamarine",
        "citrine",
        "quartz",
        "alexandrite"
       ]
      },
      "description": "Gemstone, as its slug. An alias stone (aquamarine, citrine, quartz, alexandrite) answers with the figures of the stone it shares optical constants with, and says so."
     },
     {
      "name": "sort",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "relevance",
        "total",
        "brilliance",
        "fire",
        "scintillation",
        "facets",
        "name"
       ]
      },
      "description": "relevance (default with a query), total (brilliance + fire + scintillation, the default with a gemstone and no query), brilliance, fire, scintillation, facets (most first) or name."
     },
     {
      "name": "cutting_files",
      "in": "query",
      "schema": {
       "type": "boolean"
      },
      "description": "Only cuts that are also sold as GemCad cutting files."
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 5
      },
      "description": "How many cuts to return, 1 to 50; 5 if left out."
     }
    ],
    "responses": {
     "200": {
      "description": "Matching cuts",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SearchResult"
        }
       }
      }
     },
     "404": {
      "description": "Not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/cuts/{slug}": {
   "get": {
    "operationId": "getCut",
    "summary": "One cut, in full",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "The cut's slug, as in its page address, for example asscher or t73-round-brilliant."
     }
    ],
    "responses": {
     "200": {
      "description": "The cut",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Cut"
        }
       }
      }
     },
     "404": {
      "description": "Not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/gemstones": {
   "get": {
    "operationId": "listGemstones",
    "summary": "The 30 gemstones, with their constants",
    "responses": {
     "200": {
      "description": "Gemstones",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "$ref": "#/components/schemas/Gemstone"
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/gemstones/{stone}": {
   "get": {
    "operationId": "bestCutsForGemstone",
    "summary": "A gemstone and its top ten cuts of each kind",
    "parameters": [
     {
      "name": "stone",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "diamond",
        "moissanite",
        "cubic-zirconia",
        "ruby",
        "sapphire",
        "emerald",
        "amethyst",
        "topaz",
        "spinel",
        "demantoid",
        "zircon",
        "tourmaline",
        "peridot",
        "tanzanite",
        "yag",
        "pyrope",
        "almandine",
        "spessartine",
        "grossular",
        "chrysoberyl",
        "kunzite",
        "iolite",
        "morganite",
        "ggg",
        "strontium-titanate",
        "synthetic-rutile",
        "aquamarine",
        "citrine",
        "quartz",
        "alexandrite"
       ]
      },
      "description": "The gemstone's slug. An alias stone answers with the figures of the stone it shares optical constants with."
     }
    ],
    "responses": {
     "200": {
      "description": "The gemstone",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Gemstone"
        }
       }
      }
     },
     "404": {
      "description": "Not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/gemstones/{stone}/{slug}": {
   "get": {
    "operationId": "cutInGemstone",
    "summary": "One cut in one gemstone: scores, pros and cons",
    "parameters": [
     {
      "name": "stone",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "diamond",
        "moissanite",
        "cubic-zirconia",
        "ruby",
        "sapphire",
        "emerald",
        "amethyst",
        "topaz",
        "spinel",
        "demantoid",
        "zircon",
        "tourmaline",
        "peridot",
        "tanzanite",
        "yag",
        "pyrope",
        "almandine",
        "spessartine",
        "grossular",
        "chrysoberyl",
        "kunzite",
        "iolite",
        "morganite",
        "ggg",
        "strontium-titanate",
        "synthetic-rutile",
        "aquamarine",
        "citrine",
        "quartz",
        "alexandrite"
       ]
      },
      "description": "The gemstone's slug. An alias stone answers with the figures of the stone it shares optical constants with."
     },
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "The cut's slug, as in its page address, for example asscher or t73-round-brilliant."
     }
    ],
    "responses": {
     "200": {
      "description": "The cut in the stone",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CutInGemstone"
        }
       }
      }
     },
     "404": {
      "description": "Not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/health": {
   "get": {
    "operationId": "health",
    "summary": "Status of the API",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/cut-index": {
   "get": {
    "operationId": "cutPerformanceIndex",
    "summary": "The Cut Performance Index, as its JSON download",
    "description": "The same file as https://digitalgemology.com/data/cut-performance-index.json: one row per cut and material (26 gemstones: diamond, moissanite, cubic zirconia, ruby, sapphire, emerald, amethyst, topaz, spinel, demantoid, zircon, tourmaline, peridot, tanzanite, YAG, pyrope, almandine, spessartine, grossular, chrysoberyl, kunzite, iolite, morganite, GGG, strontium titanate and synthetic rutile), unrounded scores, engine version, dataset version and each row's date. Page: https://digitalgemology.com/learn/cut-performance-index",
    "responses": {
     "200": {
      "description": "The index",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string"
     },
     "suggestions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "Product": {
    "type": "object",
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "3d_files",
       "cutting_files"
      ]
     },
     "name": {
      "type": "string"
     },
     "price_eur": {
      "type": "string"
     },
     "licence": {
      "type": "string"
     },
     "checkout": {
      "type": "string",
      "format": "uri"
     },
     "contents": {
      "type": "array",
      "items": {
       "type": "object"
      }
     }
    }
   },
   "CutSummary": {
    "type": "object",
    "properties": {
     "slug": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "url": {
      "type": "string",
      "format": "uri"
     },
     "category": {
      "type": "string"
     },
     "shape": {
      "type": "string"
     },
     "facets": {
      "type": "integer"
     },
     "size": {
      "type": "string"
     },
     "summary": {
      "type": "string"
     },
     "products": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Product"
      }
     },
     "scores": {
      "type": "object",
      "description": "In the requested gemstone, out of 100."
     }
    }
   },
   "SearchResult": {
    "type": "object",
    "properties": {
     "count": {
      "type": "integer"
     },
     "gemstone": {
      "type": "string"
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CutSummary"
      }
     }
    }
   },
   "Cut": {
    "type": "object",
    "description": "A cut in full: CutSummary plus specifications, performance in each gemstone, head-on light, FAQ and links."
   },
   "Gemstone": {
    "type": "object",
    "properties": {
     "slug": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "constants": {
      "type": "object"
     },
     "top_ten": {
      "type": "object"
     }
    }
   },
   "CutInGemstone": {
    "type": "object",
    "properties": {
     "cut": {
      "type": "string"
     },
     "gemstone": {
      "type": "string"
     },
     "headline": {
      "type": "string"
     },
     "scores": {
      "type": "object"
     },
     "pros": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "cons": {
      "type": "array",
      "items": {
       "type": "object"
      }
     }
    }
   }
  }
 }
}
