preloading the font
BonAPI | Documentation


Page Overview

Getting started

BonAPI offers 256-bit SSL encryption for all its solutions, please use the https protocol to benefit from this.
All inputs (ingredients and instructions) to the API's should be supplied in JSON formatted objects and arrays, see specific documentations for details.
All responses are returned in JSON format containing JSON response codes with details and descriptions for error responses. In order to access BonAPI's services, you must first create an account and use your BonAPI Token.

Your BonAPI Authorization Token

Your BonAPI token is necessary for authentication when making API requests through any of BonAPI’s products and solutions. It is unique to you and allows us to identify the permissions associated with your account, determining the number of allowed calls and types of parameters that can be passed together with your API requests.
You automatically receive your unique BonAPI token upon creating a BonAPI account and it is displayed in your Account page.

BonAPI Documentations

BonAPI offers several solutions designed to suit the different needs surrounding ingredient profiling, substitution and alternative suggestions. The documentations for each solution can be found in the Documentation drop down menu in the header and through the overview below.

BonAPI Solution Type Solution Description
Dynamic Recipes API API Returns updated ingredient- and instruction-lists wherein all unsuitable ingredients are substituted to conform to the provided dietary restrictions. Analysis of the instructions themselves allows for recipe specific alternatives to be found, compensating for the functional purposes of the replaced ingredients.
Recipe Profiles API API Returns the dietary profile, including diet and present allergens, as well as any requested composition data points for all ingredients in a recipe. Composition data is relative to the supplied ingredient quantities and is returned on an overall recipe basis.
Ingredient Alternatives API API Returns ingredient alternative suggestions without the need to supply any further information regarding their preparation. Single or multiple ingredients can be supplied for which all or only unsuitable ingredients will be replaced given the provided dietary requirements.
Reference APIs and Support Support Here you can find some reference APIs including an overview of all available parameters to be included in different API solutions as well as a list of example ingredients together with their dietary profile and available composition data suggested to be used when integrating BonAPI.

Response Codes

With each BonAPI request, a JSON response code is returned to indicate the success or reason for failure of the request. Response codes are provided with a detail and description.

    "response": {
        "200 Success": {
            "response_code": 200
            "detail": "A successful request and response with no identified errors or alerts."
            "description": "Indicates that request has succeeded."
        "400 Bad Request": {
            "response_code": 400
            "detail": "The criteria: <match_criteria> cannot be used as a match criteria for <ingredient_name>. Please review our documentation and reference APIs."
            "description": "The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications."
        "401 Unauthorized": {
            "response_code": 401
            "detail": "Invalid token/Authentication credentials were not provided.",
            "description": "Indicates that the request requires user authentication information. The client MAY repeat the request with a suitable Authorization header field."
        "404 Not Found": {
            "response_code": 404
            "detail": "The requested resource does not exist.",
            "description": "The server can not find the requested resource."
        "405 Method Not Allowed": {
            "response_code": 405
            "detail": "The Dynamic Recipe API only accepts POST requests. For further information please check out the documentation page.",
            "description": "The request HTTPS method is known by the server but has been disabled and cannot be used for that resource."
        "426 Upgrade Required": {
            "response_code": 426
            "detail": "The current plan does not allow the <composition> parameter. Please upgrade to a plan that allows it.",
            "description": "The server refuses to perform the request. The server will process the request after the client upgrades to a different protocol."
        "429 Too Many Requests": {
            "response_code": 429
            "detail": "Request was throttled. Expected available in x seconds.",
            "description": "The user has sent too many requests in a given amount of time."