{
  "openapi": "3.0.3",
  "info": {
    "title": "ExactCup Ingredient Density API",
    "version": "v1",
    "description": "Free read-only JSON API giving the weight in grams of one US cup (and per tablespoon, teaspoon and mL) for 80 cooking and baking ingredients. No API key, no sign-up, no rate limit, CORS enabled. Static files on GitHub Pages. Data CC BY 4.0 — attribution with a link to https://exactcup.github.io/ is required.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "ExactCup",
      "url": "https://exactcup.github.io/api/"
    }
  },
  "externalDocs": {
    "description": "Human documentation",
    "url": "https://exactcup.github.io/api/"
  },
  "servers": [
    {
      "url": "https://exactcup.github.io"
    }
  ],
  "paths": {
    "/api/v1/index.json": {
      "get": {
        "summary": "API metadata and endpoint list",
        "description": "Name, version, license, attribution requirements and every endpoint URL.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ingredients.json": {
      "get": {
        "summary": "All ingredients",
        "description": "Every ingredient with grams per US cup, tablespoon, teaspoon and mL.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "ingredients": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Ingredient"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ingredients/{slug}.json": {
      "get": {
        "summary": "One ingredient with conversion tables",
        "description": "One ingredient plus precomputed cups→grams, tablespoons→grams and grams→cups tables.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngredientDetail"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "all-purpose-flour",
                "bread-flour",
                "cake-flour",
                "whole-wheat-flour",
                "self-rising-flour",
                "almond-flour",
                "cornstarch",
                "cocoa-powder",
                "granulated-sugar",
                "brown-sugar",
                "powdered-sugar",
                "honey",
                "maple-syrup",
                "corn-syrup",
                "butter",
                "milk",
                "heavy-cream",
                "sour-cream",
                "cream-cheese",
                "yogurt",
                "vegetable-oil",
                "olive-oil",
                "coconut-oil",
                "peanut-butter",
                "chocolate-chips",
                "shredded-coconut",
                "raisins",
                "chopped-nuts",
                "rolled-oats",
                "white-rice",
                "quinoa",
                "cornmeal",
                "breadcrumbs",
                "water",
                "salt",
                "caster-sugar",
                "coconut-sugar",
                "molasses",
                "golden-syrup",
                "agave-nectar",
                "pitted-dates-chopped",
                "dried-cranberries",
                "sweetened-condensed-milk",
                "evaporated-milk",
                "buttermilk",
                "ricotta-cheese",
                "mascarpone",
                "cottage-cheese",
                "grated-parmesan",
                "shredded-cheddar",
                "shredded-mozzarella",
                "pumpkin-puree",
                "applesauce",
                "mashed-banana",
                "rye-flour",
                "oat-flour",
                "coconut-flour",
                "semolina",
                "tapioca-flour",
                "arrowroot-powder",
                "pecan-halves",
                "whole-almonds",
                "sesame-seeds",
                "chia-seeds",
                "ground-flaxseed",
                "poppy-seeds",
                "panko-breadcrumbs",
                "steel-cut-oats",
                "couscous-dry",
                "bulgur-dry",
                "pearl-barley",
                "vegetable-shortening",
                "tahini",
                "almond-butter",
                "white-chocolate-chips",
                "walnuts-chopped",
                "graham-cracker-crumbs",
                "hazelnuts",
                "cashews",
                "pine-nuts"
              ]
            }
          }
        ]
      }
    },
    "/api/v1/categories.json": {
      "get": {
        "summary": "Ingredient categories",
        "description": "Category names with the ingredient slugs in each.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/units.json": {
      "get": {
        "summary": "Unit tables",
        "description": "Volume units in mL (US, metric, imperial, Australian) and weight units in grams, with conversion formulas.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Ingredient": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Stable identifier; also the URL segment on exactcup.github.io."
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "flour",
              "sugar",
              "dairy",
              "baking",
              "grain"
            ]
          },
          "category_name": {
            "type": "string"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "grams_per_us_cup": {
            "type": "number",
            "description": "Weight in grams of one level US customary cup (236.588 mL)."
          },
          "grams_per_us_tablespoon": {
            "type": "number"
          },
          "grams_per_us_teaspoon": {
            "type": "number"
          },
          "grams_per_ml": {
            "type": "number",
            "description": "Density in g/mL — multiply by any volume in mL to get grams."
          },
          "ounces_per_us_cup": {
            "type": "number"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "IngredientDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Ingredient"
          },
          {
            "type": "object",
            "properties": {
              "conversions": {
                "type": "object",
                "properties": {
                  "cups_to_grams": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "cups": {
                          "type": "string"
                        },
                        "grams": {
                          "type": "number"
                        }
                      }
                    }
                  },
                  "tablespoons_to_grams": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "tablespoons": {
                          "type": "number"
                        },
                        "grams": {
                          "type": "number"
                        }
                      }
                    }
                  },
                  "grams_to_cups": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "grams": {
                          "type": "number"
                        },
                        "cups": {
                          "type": "number"
                        }
                      }
                    }
                  }
                }
              },
              "source": {
                "type": "string",
                "format": "uri"
              },
              "license": {
                "type": "object"
              },
              "attribution": {
                "type": "object"
              }
            }
          }
        ]
      }
    }
  }
}