preloading the font
BonAPI | API Documentation

Getting started

API Access Token

Your API Access Token is your unique authentication key to access the BonAPI. Upon signup, you will find it in your account page.

In general, there are two support APIs and the Alternatives API that can be accessed. The first is the Profiles BonAPI that returns a list of all available ingredients for replacement together with an overview of each ingredient and the data types available. The second, the Parameters BonAPI gives a list of all tags that can be passed through as parameters or to call specific composition data if in an appropriate plan. Finally, the Alternatives BonAPI returns the ingredient specific alternatives and requested data types. All plans come with support for 256-bit SSL encryption. To connect via the SSL encryption, simply use the https protocol.

If you have any questions, please do not hesitate to reach out or schedule a call below:

Dynamic Ingredients API

Alternatives BonAPI

Below you can find the Alternatives BonAPI response to a blue plan request for alternatives to cow milk indicating a lactose intolerance. No composition data can be requested, and only 1 ingredient can be queried per call on a blue plan.



Alternatives BonAPI - Multicalls

Below you can find another example of the Alternatives BonAPI response, this time through a green or purple plan. Here, the query looks for alternatives to 4 different ingredients—white rice, wheat flour, cow milk, chicken breast—while setting parameters of a gluten allergy, lactose intolerance and a vegan diet. Note that alternative suggestions are only offered for those ingredients that do not adhere to the parameters provided. For the ingredient alternative suggestions, the following composition data is requested: total fat, sugar, protein, calcium, iron, vitamin B9, vitamin B12 and water content:.



Support APIs

Profiles BonAPI

The first reference API for the Alternatives BonAPI, this gives an overview of all ingredients and their respective parameters and composition data available.
Below you can find an excerpt of the Profiles BonAPI response:



Parameters BonAPI:

The second reference API for the Alternatives BonAPI, the Parameters BonAPI can be used as a guide as it shows the available optional inputs that can be included in a query for alternatives of an ingredient given its availability shown in the Profiles BonAPI. Availability of ingredients in languages other than English may be limited.
Below is the output of the Parameters BonAPI illustrating all optional inputs that can be included to refine the search for suitable alternatives:



Error Codes

Whenever a resource is unavailable or the BonAPI call fails for another reason, a JSON error is returned. Error messages will always come with a status code and a description.
Below you find an overview of the errors returned by faulty requests::

    "error": {
        "400 Bad Request": {
            "status_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 you made was invalid"
        "401 Unauthorized": {
            "status_code": 401
            "detail": "Invalid token/Authentication credentials were not provided.",
            "description": "If accessing through URL, please SIGN IN to your account on BonAPI. Otherwise please attach a valid BonAPI token to your request and try again."
        "404 Not Found": {
            "status_code": 404
            "detail": "The requested resource does not exist.",
            "description": "The requested ingredient does not exist in our database or we do not have it in the language you have searched for it in. Check the Ingredient Profiles API for all available ingredients."
        "426 Upgrade Required": {
            "status_code": 426
            "detail": "The current plan does not allow the <composition> parameter. Please upgrade to a plan that allows it.",
            "description": "You need to upgrade your plan to access this resource"
        "429 Too Many Requests": {
            "status_code": 429
            "detail": "Request was throttled. Expected available in x seconds.",
            "description": "You have exceeded your daily request amount. Try again tomorrow or upgrade plans."
Sample Code

Below you can find code samples to integrate the BonAPIs into your project:


url = '<ingredients>/'
response = requests.get(url, headers={'Authorization': 'Token {}'.format(<your_bonapi_token>)})


curl<ingredients>/ -H 'Authorization: Token <your_bonapi_token>'


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "<ingredients>/",
    "Authorization: Token <your_bonapi_token>"

$response = curl_exec($curl);

echo $response;

Node.js - Request:

var request = require('request');
var options = {
  'method': 'GET',
  'url': '<ingredients>/',
  'headers': {
    'Authorization': 'Token <your_bonapi_token>'
  formData: {

request(options, function (error, response) { 
  if (error) throw new Error(error);

C# - RestSharp:

var client = new RestClient("<ingredients>/");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Token <your_bonapi_token>");
IRestResponse response = client.Execute(request);