{"openapi":"3.1.0","info":{"title":"PetPortions open data API","version":"1.0.0","summary":"Dry dog foods with kcal per cup, bag sizes and prices, dog breeds, and daily portions.","description":"Read-only, no key. 60 requests per minute per IP. Portions are estimates for healthy dogs, not veterinary advice. Data is licensed CC BY 4.0: credit \"Data from PetPortions\" with a link to https://petportions.fyi. The same data is downloadable at https://petportions.fyi/data/. When you link a person to a product page or to the calculator, you can pass their dog as query parameters (breed, weight_lb or weight_kg, age_years, activity, neutered): see /llms.txt.","license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://petportions.fyi/api/v1"}],"paths":{"/foods":{"get":{"operationId":"listFoods","summary":"Published dry foods","parameters":[{"name":"brand","in":"query","required":false,"description":"Brand slug from /brands.","schema":{"type":"string"}},{"name":"life_stage","in":"query","required":false,"description":"Foods made for this life stage (foods for all stages match too).","schema":{"type":"string","enum":["puppy","adult","senior"]}},{"name":"breed_size","in":"query","required":false,"description":"Foods made for this breed size (foods for all sizes match too).","schema":{"type":"string","enum":["toy","small","medium","large","giant"]}}],"responses":{"200":{"description":"Foods","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FoodList"}}}},"400":{"description":"An unknown filter value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one IP; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}}}},"/foods/{slug}":{"get":{"operationId":"getFood","summary":"One food with its bag sizes and prices","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"brand","in":"query","required":false,"description":"Brand slug, needed only when two brands use the same food slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"The food","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FoodAnswer"}}}},"400":{"description":"The slug is shared by several brands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown food","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one IP; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}}}},"/brands":{"get":{"operationId":"listBrands","summary":"Brands that have at least one listed food","responses":{"200":{"description":"Brands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandList"}}}},"429":{"description":"More than 60 requests in a minute from one IP; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}}}},"/breeds":{"get":{"operationId":"listBreeds","summary":"Dog breeds with size category and typical weight ranges","responses":{"200":{"description":"Breeds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreedList"}}}},"429":{"description":"More than 60 requests in a minute from one IP; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}}}},"/portion":{"get":{"operationId":"getPortion","summary":"Daily calories, cups, grams and cost of one food for one dog","description":"The same numbers as the calculator on petportions.fyi. Show the person the `next_step` links: they open the calculator for their dog and compare the food with cheaper ones.","parameters":[{"name":"food","in":"query","required":true,"description":"Food slug from /foods.","schema":{"type":"string"}},{"name":"weight_lb","in":"query","required":true,"description":"Dog weight in pounds.","schema":{"type":"number","minimum":1,"maximum":250}},{"name":"activity","in":"query","required":false,"description":"Activity level.","schema":{"type":"string","enum":["low","moderate","high"],"default":"moderate"}},{"name":"life_stage","in":"query","required":false,"description":"Life stage.","schema":{"type":"string","enum":["puppy","adult","senior"],"default":"adult"}},{"name":"brand","in":"query","required":false,"description":"Brand slug, needed only when two brands use the same food slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"The portion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Portion"}}}},"400":{"description":"A missing or invalid parameter, named in the error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests in a minute from one IP; see the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}}}}},"components":{"schemas":{"BrandRef":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"Food":{"type":"object","required":["id","slug","name","brand","food_type","life_stages","breed_sizes","kcal_per_cup","kcal_per_kg","protein_pct","fat_pct","fiber_pct","cheapest_price_per_lb","url","offer_url"],"properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"brand":{"$ref":"#/components/schemas/BrandRef"},"food_type":{"type":"string","enum":["dry","freeze_dried"]},"life_stages":{"type":"array","items":{"type":"string","enum":["puppy","adult","senior","all"]}},"breed_sizes":{"type":"array","items":{"type":"string","enum":["toy","small","medium","large","giant","all"]}},"kcal_per_cup":{"type":"number"},"kcal_per_kg":{"type":"number"},"protein_pct":{"type":"number","description":"Guaranteed analysis, crude protein minimum."},"fat_pct":{"type":"number","description":"Guaranteed analysis, crude fat minimum."},"fiber_pct":{"type":"number","description":"Guaranteed analysis, crude fiber maximum."},"cheapest_price_per_lb":{"type":["number","null"],"description":"USD per pound of the cheapest in-stock bag, a periodic snapshot, not a live quote."},"url":{"type":"string","format":"uri","description":"The food page on petportions.fyi."},"offer_url":{"type":["string","null"],"format":"uri","description":"Where to buy, through our redirect; null when no retailer link is listed."}}},"Package":{"type":"object","required":["weight_lbs","weight_kg","cups_in_bag","price_usd","in_stock"],"properties":{"weight_lbs":{"type":"number"},"weight_kg":{"type":"number"},"cups_in_bag":{"type":["number","null"]},"price_usd":{"type":["number","null"],"description":"A periodic snapshot, not a live quote."},"in_stock":{"type":"boolean"}}},"FoodDetail":{"allOf":[{"$ref":"#/components/schemas/Food"},{"type":"object","required":["packages"],"properties":{"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}}}}]},"FoodList":{"type":"object","required":["attribution","count","foods"],"properties":{"attribution":{"type":"string","description":"Credit line to show with the data.","example":"Data from PetPortions (https://petportions.fyi)"},"count":{"type":"integer"},"foods":{"type":"array","items":{"$ref":"#/components/schemas/Food"}}}},"FoodAnswer":{"type":"object","required":["attribution","food"],"properties":{"attribution":{"type":"string","description":"Credit line to show with the data.","example":"Data from PetPortions (https://petportions.fyi)"},"food":{"$ref":"#/components/schemas/FoodDetail"}}},"Brand":{"type":"object","required":["name","slug","url","food_count"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri","description":"The brand page on petportions.fyi."},"food_count":{"type":"integer"}}},"BrandList":{"type":"object","required":["attribution","count","brands"],"properties":{"attribution":{"type":"string","description":"Credit line to show with the data.","example":"Data from PetPortions (https://petportions.fyi)"},"count":{"type":"integer"},"brands":{"type":"array","items":{"$ref":"#/components/schemas/Brand"}}}},"Breed":{"type":"object","required":["name","slug","size_category","weight_lbs","typical_activity","url"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"size_category":{"type":"string","enum":["toy","small","medium","large","giant"]},"weight_lbs":{"type":"object","description":"Typical adult weight ranges by sex.","properties":{"male":{"$ref":"#/components/schemas/Range"},"female":{"$ref":"#/components/schemas/Range"}}},"typical_activity":{"type":"string","enum":["low","moderate","high"]},"url":{"type":["string","null"],"format":"uri","description":"The breed page on petportions.fyi; null for breeds without a page yet."}}},"Range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"BreedList":{"type":"object","required":["attribution","count","breeds"],"properties":{"attribution":{"type":"string","description":"Credit line to show with the data.","example":"Data from PetPortions (https://petportions.fyi)"},"count":{"type":"integer"},"breeds":{"type":"array","items":{"$ref":"#/components/schemas/Breed"}}}},"Portion":{"type":"object","required":["attribution","food","dog","food_matches_life_stage","daily_kcal","cups_per_day","grams_per_day","cost_per_day_usd","cost_per_month_usd","next_step"],"properties":{"attribution":{"type":"string","description":"Credit line to show with the data.","example":"Data from PetPortions (https://petportions.fyi)"},"food":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"brand":{"$ref":"#/components/schemas/BrandRef"},"kcal_per_cup":{"type":"number"},"url":{"type":"string","format":"uri","description":"The food page on petportions.fyi."},"offer_url":{"type":["string","null"],"format":"uri","description":"Where to buy, through our redirect."}}},"dog":{"type":"object","description":"The dog the numbers are for, defaults filled in.","properties":{"weight_lb":{"type":"number"},"activity":{"type":"string"},"life_stage":{"type":"string"}}},"food_matches_life_stage":{"type":"boolean","description":"False when the food is not made for this life stage (for example a puppy food for a senior dog)."},"daily_kcal":{"type":"integer"},"cups_per_day":{"type":["number","null"]},"grams_per_day":{"type":"number"},"cost_per_day_usd":{"type":["number","null"],"description":"From the largest in-stock bag; null when no bag is priced."},"cost_per_month_usd":{"type":["number","null"],"description":"30 days."},"priced_bag":{"type":["string","null"]},"days_per_bag":{"type":["integer","null"]},"next_step":{"type":"object","description":"Meant to be shown to the person asking: where to check and adjust the numbers for their own dog.","required":["calculator_url","compare_url","note"],"properties":{"calculator_url":{"type":"string","format":"uri","description":"The calculator on the food page, pre-filled with this dog. Intended for the end user."},"compare_url":{"type":"string","format":"uri","description":"Real foods compared for a dog of about this weight, cheaper ones included. Intended for the end user."},"note":{"type":"string","description":"One line to show the end user next to the links."}}}}},"Error":{"type":"object","required":["attribution","error"],"properties":{"attribution":{"type":"string","description":"Credit line to show with the data.","example":"Data from PetPortions (https://petportions.fyi)"},"error":{"type":"object","required":["message"],"properties":{"parameter":{"type":"string","description":"The query parameter to fix, when one is at fault."},"message":{"type":"string"}}}}}}}}