{
 "openapi": "3.1.0",
 "info": {
  "title": "Digital Gemology cut library API",
  "version": "1.0.0",
  "description": "Read-only, free, no key. Search 44 gem cuts and Platonic solids, their measured specifications, brilliance, fire and scintillation in seven 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"
 },
 "servers": [
  {
   "url": "https://digitalgemology.com"
  }
 ],
 "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"
       ]
      },
      "description": "Gemstone, as its slug."
     },
     {
      "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": 10
      },
      "description": ""
     }
    ],
    "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 seven 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"
       ]
      }
     }
    ],
    "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"
       ]
      }
     },
     {
      "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"
        }
       }
      }
     }
    }
   }
  }
 },
 "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"
      }
     }
    }
   }
  }
 }
}