{
  "openapi": "3.1.0",
  "info": {
    "title": "Open Food Facts folksonomy REST API",
    "description": "\nFolksonomy Engine API allows you to add free property/value pairs to Open Food Facts products.\n\nThe API use the main following variables:\n* **product**: the product number\n* **k**: \"key\", meaning the property or tag\n* **v**: \"value\", the value for a related key\n\n## See also\n\n* [Project page](https://wiki.openfoodfacts.org/Folksonomy_Engine)\n* [Folksonomy Engine github repository](https://github.com/openfoodfacts/folksonomy_engine)\n* [Documented properties](https://wiki.openfoodfacts.org/Folksonomy/Property)\n",
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://api.folksonomy.openfoodfacts.org",
      "description": "Production server"
    },
    {
      "url": "http://localhost:8000",
      "description": "Local development server"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["System"],
        "summary": "Hello",
        "operationId": "hello__get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HelloResponse"
                }
              }
            }
          }
        }
      }
    },
    "/auth": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Authentication",
        "description": "Authentication: provide user/password and get a bearer token in return\n\n- **username**: Open Food Facts user_id (not email)\n- **password**: user password (clear text, but HTTPS encrypted)\n\ntoken is returned, to be used in later requests with usual \"Authorization: bearer token\" headers",
        "operationId": "authentication_auth_post",
        "parameters": [
          {
            "name": "session",
            "in": "cookie",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Session"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/Body_authentication_auth_post"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/auth_by_cookie": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Authentication By Cookie",
        "description": "Authentication: provide Open Food Facts session cookie and get a bearer token in return\n\n- **session cookie**: Open Food Facts session cookie\n\ntoken is returned, to be used in later requests with usual \"Authorization: bearer token\" headers",
        "operationId": "authentication_by_cookie_auth_by_cookie_post",
        "parameters": [
          {
            "name": "session",
            "in": "cookie",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Session"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/products/stats": {
      "get": {
        "tags": ["Products"],
        "summary": "Product Stats",
        "description": "Get the list of products with tags statistics\n\nThe products list can be limited to some tags (k or k=v)",
        "operationId": "product_stats_products_stats_get",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "default": "",
              "title": "Owner"
            }
          },
          {
            "name": "k",
            "in": "query",
            "required": false,
            "schema": {
              "default": "",
              "title": "K"
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "schema": {
              "default": "",
              "title": "V"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProductStats"
                  },
                  "title": "Response Product Stats Products Stats Get"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/products": {
      "get": {
        "tags": ["Products"],
        "summary": "Product List",
        "description": "Get the list of products matching k or k=v",
        "operationId": "product_list_products_get",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "default": "",
              "title": "Owner"
            }
          },
          {
            "name": "k",
            "in": "query",
            "required": false,
            "schema": {
              "default": "",
              "title": "K"
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "schema": {
              "default": "",
              "title": "V"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProductList"
                  },
                  "title": "Response Product List Products Get"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/product/{product}": {
      "get": {
        "tags": ["Product Tags"],
        "summary": "Product Tags List",
        "description": "Get a list of existing tags for a product, optionally filtering by specific keys.",
        "operationId": "product_tags_list_product__product__get",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Product"
            }
          },
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "",
              "title": "Owner"
            }
          },
          {
            "name": "keys",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Comma-separated list of keys to filter by. If not provided, all keys are returned.",
              "title": "Keys"
            },
            "description": "Comma-separated list of keys to filter by. If not provided, all keys are returned."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProductTag"
                  },
                  "title": "Response Product Tags List Product  Product  Get"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/product/{product}/{k}": {
      "get": {
        "tags": ["Product Tags"],
        "summary": "Product Tag",
        "description": "Get a specific tag or tag hierarchy on a product\n\n- /product/xxx/key returns only the requested key\n- /product/xxx/key* returns the key and subkeys (key:subkey)",
        "operationId": "product_tag_product__product___k__get",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Product"
            }
          },
          {
            "name": "k",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "K"
            }
          },
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "default": "",
              "title": "Owner"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductTag"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Product Tags"],
        "summary": "Product Tag Delete",
        "description": "Delete a product tag",
        "operationId": "product_tag_delete_product__product___k__delete",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Product"
            }
          },
          {
            "name": "k",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "K"
            }
          },
          {
            "name": "version",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "title": "Version"
            }
          },
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "default": "",
              "title": "Owner"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/product/{product}/{k}/versions": {
      "get": {
        "tags": ["Product Tags"],
        "summary": "Product Tag List Versions",
        "description": "Get a list of all versions of a tag for a product",
        "operationId": "product_tag_list_versions_product__product___k__versions_get",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "product",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Product"
            }
          },
          {
            "name": "k",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "K"
            }
          },
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "default": "",
              "title": "Owner"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProductTag"
                  },
                  "title": "Response Product Tag List Versions Product  Product   K  Versions Get"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/product": {
      "put": {
        "tags": ["Product Tags"],
        "summary": "Product Tag Update",
        "description": "Update a product tag\n\n- **product**: which product\n- **k**: which key for the tag\n- **v**: which value to set for the tag\n- **version**: must be equal to previous version + 1\n- **owner**: None or empty for public tags, or your own user_id",
        "operationId": "product_tag_update_product_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductTag"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      },
      "post": {
        "tags": ["Product Tags"],
        "summary": "Product Tag Add",
        "description": "Create a new product tag (version=1)\n\n- **product**: which product\n- **k**: which key for the tag\n- **v**: which value to set for the tag\n- **version**: none or empty or 1\n- **owner**: none or empty for public tags, or your own user_id\n\nBe aware it's not possible to create the same tag twice. Though, you can update\na tag and add multiple values the way you want (don't forget to document how); comma\nseparated list is a good option.",
        "operationId": "product_tag_add_product_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductTag"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ]
      }
    },
    "/keys": {
      "get": {
        "tags": ["Keys & Values"],
        "summary": "Keys List",
        "description": "Get the list of keys with statistics, with an optional search filter.\n\nThe keys list can be restricted to private tags from some owner",
        "operationId": "keys_list_keys_get",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": "",
              "title": "Q"
            }
          },
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "",
              "title": "Owner"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/KeyStats"
                  },
                  "title": "Response Keys List Keys Get"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/values/{k}": {
      "get": {
        "tags": ["Keys & Values"],
        "summary": "Get Unique Values",
        "description": "Get the unique values of a given property and the corresponding number of products\n\n- **k**: The property key to get unique values for\n- **owner**: None or empty for public tags, or your own user_id\n- **q**: Filter values by a query string\n- **limit**: Maximum number of values to return (default: 50; max: 1000)",
        "operationId": "get_unique_values_values__k__get",
        "security": [
          {
            "OAuth2PasswordBearer": []
          }
        ],
        "parameters": [
          {
            "name": "k",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "K"
            }
          },
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "",
              "title": "Owner"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "",
              "title": "Q"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "title": "Limit"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ValueCount"
                  },
                  "title": "Response Get Unique Values Values  K  Get"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/ping": {
      "get": {
        "tags": ["System"],
        "summary": "Pong",
        "description": "Check server health",
        "operationId": "pong_ping_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PingResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Body_authentication_auth_post": {
        "properties": {
          "grant_type": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^password$"
              },
              {
                "type": "null"
              }
            ],
            "title": "Grant Type"
          },
          "username": {
            "type": "string",
            "title": "Username"
          },
          "password": {
            "type": "string",
            "title": "Password"
          },
          "scope": {
            "type": "string",
            "title": "Scope",
            "default": ""
          },
          "client_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Client Id"
          },
          "client_secret": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Client Secret"
          }
        },
        "type": "object",
        "required": ["username", "password"],
        "title": "Body_authentication_auth_post"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "HelloResponse": {
        "properties": {
          "message": {
            "type": "string",
            "title": "Message"
          }
        },
        "type": "object",
        "required": ["message"],
        "title": "HelloResponse"
      },
      "KeyStats": {
        "properties": {
          "k": {
            "type": "string",
            "title": "K"
          },
          "count": {
            "type": "integer",
            "title": "Count"
          },
          "values": {
            "type": "integer",
            "title": "Values"
          }
        },
        "type": "object",
        "required": ["k", "count", "values"],
        "title": "KeyStats"
      },
      "PingResponse": {
        "properties": {
          "ping": {
            "type": "string",
            "title": "Ping"
          }
        },
        "type": "object",
        "required": ["ping"],
        "title": "PingResponse"
      },
      "ProductList": {
        "properties": {
          "product": {
            "type": "string",
            "title": "Product"
          },
          "k": {
            "type": "string",
            "title": "K"
          },
          "v": {
            "type": "string",
            "title": "V"
          }
        },
        "type": "object",
        "required": ["product", "k", "v"],
        "title": "ProductList"
      },
      "ProductStats": {
        "properties": {
          "product": {
            "type": "string",
            "title": "Product"
          },
          "keys": {
            "type": "integer",
            "title": "Keys"
          },
          "editors": {
            "type": "integer",
            "title": "Editors"
          },
          "last_edit": {
            "type": "string",
            "format": "date-time",
            "title": "Last Edit"
          }
        },
        "type": "object",
        "required": ["product", "keys", "editors", "last_edit"],
        "title": "ProductStats"
      },
      "ProductTag": {
        "properties": {
          "product": {
            "type": "string",
            "title": "Product"
          },
          "k": {
            "type": "string",
            "title": "K"
          },
          "v": {
            "type": "string",
            "title": "V"
          },
          "owner": {
            "type": "string",
            "title": "Owner",
            "default": ""
          },
          "version": {
            "type": "integer",
            "title": "Version",
            "default": 1
          },
          "editor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Editor"
          },
          "last_edit": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Edit"
          },
          "comment": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Comment",
            "default": ""
          }
        },
        "type": "object",
        "required": ["product", "k", "v"],
        "title": "ProductTag"
      },
      "TokenResponse": {
        "properties": {
          "access_token": {
            "type": "string",
            "title": "Access Token"
          },
          "token_type": {
            "type": "string",
            "title": "Token Type"
          }
        },
        "type": "object",
        "required": ["access_token", "token_type"],
        "title": "TokenResponse"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": ["loc", "msg", "type"],
        "title": "ValidationError"
      },
      "ValueCount": {
        "properties": {
          "v": {
            "type": "string",
            "title": "V"
          },
          "product_count": {
            "type": "integer",
            "title": "Product Count"
          }
        },
        "type": "object",
        "required": ["v", "product_count"],
        "title": "ValueCount"
      }
    },
    "securitySchemes": {
      "OAuth2PasswordBearer": {
        "type": "oauth2",
        "flows": {
          "password": {
            "scopes": {},
            "tokenUrl": "auth"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "System",
      "description": "System health and general API information"
    },
    {
      "name": "Authentication",
      "description": "User authentication and authorization endpoints"
    },
    {
      "name": "Products",
      "description": "Product discovery and statistics"
    },
    {
      "name": "Product Tags",
      "description": "CRUD operations for product tags and properties"
    },
    {
      "name": "Keys & Values",
      "description": "Browse available keys and their possible values"
    }
  ]
}