{
  "openapi": "3.1.0",
  "info": {
    "title": "Suffering Footprint API",
    "version": "1.1.0",
    "description": "Ranks animals by suffering per individual (welfare range × P(sentience) × condition intensity × duration); also compares foods per kg, kcal or protein: animals, farmed days and welfare-weighted suffering-days. Per-kg values count animals per kg; for how much each animal suffers use /api/hierarchy or basis=individual. Inputs that are editorial estimates are listed in assume[]. Free, no key, CORS enabled. Also available as an MCP server at https://sufferingfootprint.com/mcp."
  },
  "servers": [
    {
      "url": "https://sufferingfootprint.com"
    }
  ],
  "paths": {
    "/api/hierarchy": {
      "get": {
        "operationId": "rankAnimalsPerIndividual",
        "summary": "Rank animals by suffering per individual",
        "description": "Rows: id, name, group, system, p, wr, condition_intensity, duration_days, per_day_intensity, per_individual {score, low, high}, band (A ≥ 50, B 10–50, C 1–10, D < 1, none), assume[], sources[], rank, rank_per_day. Includes food animals, breeding sows (kind farm) and lab macaques (kind lab).",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "food",
                "lab",
                "all"
              ],
              "default": "all"
            }
          },
          {
            "name": "include_slaughter",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "vertebrates_only",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/species": {
      "get": {
        "operationId": "getSpecies",
        "summary": "Any food or animal, including non-food animals (breeding sow, lab macaque)",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sow"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/foods": {
      "get": {
        "operationId": "listFoods",
        "summary": "List all foods with footprints, per_individual and per_day_intensity",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/foods/{id}": {
      "get": {
        "operationId": "getFood",
        "summary": "One food with every input and source. Non-food animals return 400 (not a food).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Food id or alias",
              "example": "chicken"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/footprint": {
      "get": {
        "operationId": "footprintGet",
        "summary": "Footprint of one food or a short list. Non-food animals (e.g. lab macaque) return 400.",
        "parameters": [
          {
            "name": "food",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Food id or alias",
              "example": "chicken"
            }
          },
          {
            "name": "grams",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "kcal",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "protein_g",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "items",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "chicken:200,rice:150"
            },
            "description": "Comma-separated food:grams pairs"
          },
          {
            "name": "times",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "include_slaughter",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "footprintPost",
        "summary": "Footprint of a meal, recipe or diet",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "items"
                ],
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "food"
                      ],
                      "properties": {
                        "food": {
                          "type": "string",
                          "description": "Food id or alias: plants, fungi, milk, beef, pork, turkey, chicken, chickenbcc, eggscage, eggsfree, salmon, catfish, shrimp, crickets, mussels, oysters",
                          "example": "chicken"
                        },
                        "grams": {
                          "type": "number"
                        },
                        "kcal": {
                          "type": "number"
                        },
                        "protein_g": {
                          "type": "number"
                        }
                      }
                    }
                  },
                  "times": {
                    "type": "number"
                  },
                  "include_slaughter": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/compare": {
      "get": {
        "operationId": "compareFoods",
        "summary": "Rank foods",
        "description": "Default basis kcal. basis=individual ranks by suffering per animal behind each food. Per-kg/kcal/protein responses carry a note: they count animals per unit of food.",
        "parameters": [
          {
            "name": "foods",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "beef,chicken,shrimp"
            }
          },
          {
            "name": "basis",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "kg",
                "kcal",
                "protein",
                "individual"
              ],
              "default": "kcal"
            }
          },
          {
            "name": "include_slaughter",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/method": {
      "get": {
        "operationId": "method",
        "summary": "Per-individual and per-kg formulas, units and exclusions",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/data": {
      "get": {
        "operationId": "data",
        "summary": "Full dataset with all sources, including non-food animals (other_animals) and the per-individual ranking",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}