Introduction

The Trustwell Genesis Foods API provides a powerful way to access food data, perform analyses, query standard entities, and create new ingredients or recipes. Built on GraphQL, the API allows you to define precisely what data you need and retrieve it efficiently. This guide will walk you through how to authenticate and start making queries and mutations using the API.

Obtaining your API Key

Only Administrators with API Access will have the ability to generate an API Key.
Treat your API Key like a password. Keep it secret; keep it safe.

To start using the Genesis Foods API, follow these steps:

Log into the Genesis Foods application.
In the lower left, click the vertical ellipsis next to your Organization Name / Username.
Select Profile.
Select API Tokens along the top.
Click Create API Token.
Enter a Label.
Click Create Token.
Once created, we recommend using the Copy button to copy the string to the clipboard.
- Important: This is the only time you will be able to obtain this Token. Should this be lost, the Token should be deleted and a new one created.
- Preserve this Token string as you would other secrets / passwords.
Include this API Key in the request headers for every request you make.

Example API Key Format

{ 
  "X-API-KEY": "XXXYYYYBBBBZZZZ" 
}

Notes

The API enforces rate and usage limits.
Requests are only processed over HTTPS. HTTP requests will be redirected to the corresponding HTTPS resource.
The Genesis Foods API uses GraphQL and has a single endpoint. For more information on how GraphQL works, please visit http://graphql.org.

Authentication/Authorization

You can generate an API Key through the Genesis Foods application, provided your user has the necessary permissions. If you do not have access to generate API Keys, please contact your Account Manager for assistance.

Include your API Key in the request headers

{ 
  "X-API-KEY": "XXXYYYYBBBBZZZZ" 
}

API Reference Documentation

https://docs.trustwell.com/genesis/api/

API Operations: Queries and Mutations Examples

The Trustwell Genesis Foods API offers a range of operations that allow you to interact with the system through both queries and mutations. Queries enable you to fetch data, such as searching for foods or retrieving nutritional analysis, while mutations allow you to create or update data, like adding ingredients or recipes. Each operation is designed to be flexible and powerful, giving you control over the specific data you need and minimizing unnecessary overhead.

Below are examples of common API operations, showing how to construct requests and handle responses for both queries and mutations.

Genesis GraphQL API Endpoint

Production: https://api.trustwell.com/genesis

Preview: https://api-preview.trustwell.com/genesis

note

In the examples below, many responses have been truncated for readability.

Searching

Searching for foods is a key action that users utilize to build recipes.

Search results are paginated.

Query

query($input: FoodSearchInput!){
    foods{
        search(input: $input)
        {
            foodSearchResults{
                id
                name
                modified
                created
                versionName
                foodType
                product
                supplier
                isApproved
                versionHistoryId
            }
            totalCount
            pageInfo{
                cursor
                hasNextPage
                startCursor
                endCursor
            }
        }
    }
}

GraphQL Variables

{
    "input":{
        "searchText":"recipe",
        "foodTypes":["Ingredient", "Recipe"],
        "itemSourceFilter":"All",
        "versionFilter":"Latest"
    }
}

"data": {
        "foods": {
            "search": {
                "foodSearchResults": [
                    ...
                    {
                        "id": "423f0ddd-14b2-4114-8323-7f8ccc11ddac",
                        "name": "granola, prepared from recipe",
                        "modified": "2023-03-27T16:57:27.4906008+00:00",
                        "created": "2023-03-27T16:57:27.4838005+00:00",
                        "versionName": "V1",
                        "foodType": "Ingredient",
                        "product": "USDA",
                        "supplier": "USDA SR-Legacy",
                        "isApproved": true,
                        "versionHistoryId": "4b7f32ab-3bae-469d-bce8-2dfd28b726d0"
                    },
                    {
                        "id": "21b52b33-2fde-498e-9a44-5023f98260b4",
                        "name": "taffy, prepared from recipe",
                        "modified": "2023-03-27T18:53:40.3575528+00:00",
                        "created": "2023-03-27T18:53:40.3504859+00:00",
                        "versionName": "V1",
                        "foodType": "Ingredient",
                        "product": "Canadian Nutrient File",
                        "supplier": "Health Canada (Canadian Nutrient File)",
                        "isApproved": true,
                        "versionHistoryId": "fb308722-32c1-45c8-8666-42ba8e0a329c"
                    },
                    {
                        "id": "a7eaee32-6ecd-4ece-90d0-48300d9d4439",
                        "name": "divinity, prepared from recipe",
                        "modified": "2023-03-27T17:44:05.6121672+00:00",
                        "created": "2023-03-27T17:44:05.6036143+00:00",
                        "versionName": "V1",
                        "foodType": "Ingredient",
                        "product": "USDA",
                        "supplier": "USDA SR-Legacy",
                        "isApproved": true,
                        "versionHistoryId": "db00f784-1a0d-4b14-a4cd-dd53b8487475"
                    },
                    ...
                ],
                "totalCount": 1407,
                "pageInfo": {
                    "cursor": 10,
                    "hasNextPage": true,
                    "startCursor": 0,
                    "endCursor": 1407
                }
            }
        }
    }
}

Getting an Analysis

Analyzing your foods is a core use case for Genesis. There are 2 types of analyses you can request: Gross and Net.

Query

query($input : GetAnalysisInput!){
    analysis{
        getAnalysis(input: $input){
            analysis{
                analysisType
                nutrientInfos{
                    nutrient{
                        id
                        name
                    }
                    value
                }
                amountAnalyzed{
                    quantity{
                        value
                    }
                    unit{
                        name
                    }
                }
                weight{
                   quantity{
                        value
                    }
                    unit{
                        name
                    } 
                }
            }
        }
    } 
}

GraphQL Variables

{
    "input":{
        "foodId":"855f573f-9977-4625-8241-c6a3ee847b84",
        "analysisInput":{
            "analysisType": "Net",
            "amount":{
                "quantity":"100",
                "unitId":"a7df0af5-0008-0000-7484-751e8eaf05c6"
            }
        }
    }
}

"data": {
        "analysis": {
            "getAnalysis": {
                "analysis": {
                    "analysisType": "Net",
                    "nutrientInfos": [
                        {
                            "nutrient": {
                                "id": "84a8709a-0000-0000-ebf9-90cea7d9d44f",
                                "name": "Calories"
                            },
                            "value": 258
                        },
                        {
                            "nutrient": {
                                "id": "84a8709a-0001-0000-ebf9-90cea7d9d44f",
                                "name": "Protein"
                            },
                            "value": 5.9
                        },
                        {
                            "nutrient": {
                                "id": "84a8709a-0002-0000-ebf9-90cea7d9d44f",
                                "name": "Carbohydrates"
                            },
                            "value": 57.8
                        },                        
                        {
                            "nutrient": {
                                "id": "84a8709a-00cf-0000-ebf9-90cea7d9d44f",
                                "name": "Salt"
                            },
                            "value": 1.8725
                        },
                        ...
                    ],
                    "amountAnalyzed": {
                        "quantity": {
                            "value": "100"
                        },
                        "unit": {
                            "name": "Gram"
                        }
                    },
                    "weight": {
                        "quantity": {
                            "value": "100"
                        },
                        "unit": {
                            "name": "Gram"
                        }
                    }
                }
            }
        }
    }
}

Querying Standard Entities

There are several examples of standard entities in the data. These include units of measure, products, suppliers, etc.

Query

query{
    units{
        getStandard
        {
            units{
                id
                name
                dimension
            }
        }
    } 
}

{
    "data": {
        "units": {
            "getStandard": {
                "units": [
                    {
                        "id": "f14819b2-e1b6-4f8b-9b85-08d43583ec09",
                        "name": "Individual Carton",
                        "dimension": "Discrete"
                    },
                    {
                        "id": "e92dc923-6da8-4fe1-9380-6564201d70c2",
                        "name": "Kit",
                        "dimension": "Discrete"
                    },
                    {
                        "id": "a7df0af5-0001-0000-7484-751e8eaf05c6",
                        "name": "Teaspoon",
                        "dimension": "Volume"
                    },
                    {
                        "id": "a7df0af5-0002-0000-7484-751e8eaf05c6",
                        "name": "Tablespoon",
                        "dimension": "Volume"
                    },
                    {
                        "id": "a7df0af5-0003-0000-7484-751e8eaf05c6",
                        "name": "Cup",
                        "dimension": "Volume"
                    },
                    ...            
                ]
            }
        }
    }
}

Creating an Ingredient

Mutation

mutation($input : CreateFoodInput!){
    foods{
        create(input:$input)
        {
            food{
                id
                name
                definingAmount{
                    quantity{
                        value
                    }
                    unit{
                        id
                        name
                    }
                }
                conversions{
                    from{
                        quantity{
                            value
                        }
                        unit{
                            id
                            name
                        }
                    }
                    to{
                        quantity{
                            value
                        }
                        unit{
                            id
                            name
                        }
                    }
                }
            }
        }
    }
}

GraphQL Variables

{
    "input":{
        "name":"Test Ingredient Name",
        "foodType":"Ingredient"
    }
}

{
    "data": {
        "foods": {
            "create": {
                "food": {
                    "id": "bd975a4b-5bc0-4e8a-885d-a9c1f586125b",
                    "name": "Test Ingredient Name",
                    "definingAmount": {
                        "quantity": {
                            "value": "100"
                        },
                        "unit": {
                            "id": "a7df0af5-0008-0000-7484-751e8eaf05c6",
                            "name": "Gram"
                        }
                    },
                    "conversions": [
                        {
                            "from": {
                                "quantity": {
                                    "value": "1"
                                },
                                "unit": {
                                    "id": "a7df0af5-0063-0000-7484-751e8eaf05c6",
                                    "name": "Batch Weight"
                                }
                            },
                            "to": {
                                "quantity": {
                                    "value": "100"
                                },
                                "unit": {
                                    "id": "a7df0af5-0008-0000-7484-751e8eaf05c6",
                                    "name": "Gram"
                                }
                            }
                        },
                        {
                            "from": {
                                "quantity": {
                                    "value": "100"
                                },
                                "unit": {
                                    "id": "a7df0af5-0008-0000-7484-751e8eaf05c6",
                                    "name": "Gram"
                                }
                            },
                            "to": {
                                "quantity": {
                                    "value": "1"
                                },
                                "unit": {
                                    "id": "a7df0af5-0064-0000-7484-751e8eaf05c6",
                                    "name": "Batch Yield"
                                }
                            }
                        }
                    ]
                }
            }
        }
    }
}

Creating a Recipe

Mutation

mutation($input : CreateFoodInput!){
    foods{
        create(input:$input)
        {
            food{
                id
                name
                }
            }
        }
}

GraphQL Variables

{
    "input":{
        "name":"Test Recipe Name",
        "foodType":"Recipe"
    }
}

{
    "data": {
        "foods": {
            "create": {
                "food": {
                    "id": "0f33eb79-7ba1-48eb-acd6-1f8c22858cea",
                    "name": "Test Recipe Name"
                }
            }
        }
    }
}