Folksonomy Engine API

{"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","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_authentication_auth_post"}}},"required":true},"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"}}}}}}},"/admin/property/check-clash":{"post":{"tags":["Admin - Property Management"],"summary":"Check Property Clash","description":"Check for potential clashes when renaming a property\n\nReturns information about products that would be affected by the rename:\n- **old_property**: The current property name\n- **new_property**: The target property name\n\nReturns counts and list of conflicting products where both properties exist","operationId":"check_property_clash_admin_property_check_clash_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyClashCheckRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyClashCheck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/admin/property/rename":{"post":{"tags":["Admin - Property Management"],"summary":"Rename Property","description":"Rename a property across all products\n\nWhen renaming a property that already exists:\n- If both properties have the same value: keep one entry\n- If both properties have different values: keep the original property's value\n\n- **old_property**: The current property name\n- **new_property**: The target property name","operationId":"rename_property_admin_property_rename_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyRenameRequest"}}},"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":[]}]}},"/admin/property":{"delete":{"tags":["Admin - Property Management"],"summary":"Delete Property","description":"Delete a property from all products\n\n- **property**: The property name to delete","operationId":"delete_property_admin_property_delete","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyDeleteRequest"}}},"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":[]}]}},"/user/me":{"get":{"summary":"Get User Info","description":"Get current user roles (admin, moderator, user)","operationId":"get_user_info_user_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"OAuth2PasswordBearer":[]}]}},"/admin/value/replace":{"post":{"tags":["Admin - Value Management"],"summary":"Replace Value","description":"Replace a value for a specific property across all products\n\n- **property**: The property name\n- **old_value**: The value to replace\n- **new_value**: The new value","operationId":"replace_value_admin_value_replace_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValueRenameRequest"}}},"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":[]}]}},"/admin/value":{"delete":{"tags":["Admin - Value Management"],"summary":"Delete Value","description":"Delete a specific value for a property from all products\n\n- **property**: The property name\n- **value**: The value to delete","operationId":"delete_value_admin_value_delete","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValueDeleteRequest"}}},"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":[]}]}}},"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"},"PropertyClashCheck":{"properties":{"products_with_both":{"type":"integer","title":"Products With Both"},"products_with_old_only":{"type":"integer","title":"Products With Old Only"},"products_with_new_only":{"type":"integer","title":"Products With New Only"},"conflicting_products":{"items":{},"type":"array","title":"Conflicting Products"}},"type":"object","required":["products_with_both","products_with_old_only","products_with_new_only","conflicting_products"],"title":"PropertyClashCheck"},"PropertyClashCheckRequest":{"properties":{"old_property":{"type":"string","title":"Old Property"},"new_property":{"type":"string","title":"New Property"}},"type":"object","required":["old_property","new_property"],"title":"PropertyClashCheckRequest"},"PropertyDeleteRequest":{"properties":{"property":{"type":"string","title":"Property"}},"type":"object","required":["property"],"title":"PropertyDeleteRequest"},"PropertyRenameRequest":{"properties":{"old_property":{"type":"string","title":"Old Property"},"new_property":{"type":"string","title":"New Property"}},"type":"object","required":["old_property","new_property"],"title":"PropertyRenameRequest"},"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"},"ValueDeleteRequest":{"properties":{"property":{"type":"string","title":"Property"},"value":{"type":"string","title":"Value"}},"type":"object","required":["property","value"],"title":"ValueDeleteRequest"},"ValueRenameRequest":{"properties":{"property":{"type":"string","title":"Property"},"old_value":{"type":"string","title":"Old Value"},"new_value":{"type":"string","title":"New Value"}},"type":"object","required":["property","old_value","new_value"],"title":"ValueRenameRequest"}},"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"}]}