Notion has a simple API that allows you to easily report on any of your ingredients and is a great way to import historical data. Reporting on ingredients through the API requires that an ingredient exists first.

1. Prep Work

During the recipe creation process, you will need to assign each ingredient to an email address, just like you would for a manually reported ingredient. As outlined below, you will later override that assignment by using the API.

For this reason, we recommend you assign the ingredients to yourself or to who ever is going to be setting up the API to avoid user confusion.

On the API control panel page, you will see your unique API token (yellow) for your company account, as well the ID tokens (green) for every public recipe.

With these two bits of information, you have everything you need to get started.

Additional Information

Once an ingredient is being reported on via the API, email reminders will no longer be sent to the original reporter.

  • This is the case even if you only run the API manually or once, instead of on a cron job.
  • If you used the API to upload historical data and now want to set the ingredient back to manual reporting, find the ingredient and hit the "Disable" button. Email reminders will begin sending based on the initial frequency of the recipe.

2. Authentication

When making API requests, you will authenticate yourself by including your API token in the Authorization header:

Authorization: <your_api_key>

Example Request

curl -H "Authorization: 12d47e568ae8b6e8ce876ab3" \
  -H "Content-Type: application/json" \
  https://app.usenotion.com/api/v1/echo

The server will respond with a status of 200 OK and the following body:

{
  "hello": "world",
  "status": "ok"
}

3. Reporting Ingredient Data

Reporting a Single Value

To report a single value only for an ingredient, make a POST request with a JSON body to the reporting endpoint at https://app.usenotion.com/api/v1/report. The request JSON body contains three keys:

{
  "ingredient_id": "4e62abc61822bc23026c2978",
  "value": 985.26,
  "date": "2016-04-01"
}
  • ingredient_id (string) is the token identifying the ingredient on which to report. The ingredient tokens are listed on the API Control Panel in the "Ingredient ID" column.
  • value (integer or float) can be a negative or positive.
  • date (string) must be formatted as YYYY-MM-DD.

Example Request

curl -H "Authorization: 12d47e568ae8b6e8ce876ab3" \
  -H "Content-Type: application/json" \
  -d '{"ingredient_id": "4e62abc61822bc23026c2978", "value": 1234.11, "date": "2016-04-01"}' \
  https://app.usenotion.com/api/v1/report

The server will respond with a status of 201 Created and the following body:

{
  "errors": [],
  "status": "created"
}

If there are any errors processing your request, the server will return a 400 Bad Request and the errors will appear in the errors list.

Reporting many values at once

To report a series of values for an ingredient, make a POST request with a JSON body to the reporting endpoint at https://app.usenotion.com/api/v1/batch_report. The request JSON body contains three keys:

{     
    "ingredient_id": "4e62abc61822bc23026c2978", 
    "reports": [
        {
            "value": 110000,
            "date": "2016-08-23"
        },
        {
            "value": 121000,
            "date": "2016-08-16"
        },
        {
            "value": 133100,
            "date": "2016-08-09"
        },
        {
            "value": 146410,
            "date": "2016-08-02"
        }
    ] 
} 
  • ingredient_id (string) is the token identifying the ingredient on which to report. The ingredient tokens are listed on the API Control Panel in the "Ingredient ID" column.
  • reports (array) is the array of value / date pairs.
  • value (integer or float) can be a negative or positive.
  • date (string) must be formatted as YYYY-MM-DD.

Example Request

curl -H "Authorization: 12d47e568ae8b6e8ce876ab3" \ 
    -H "Content-Type: application/json" \ 
    -d '{"ingredient_id": "4e62abc61822bc23026c2978", "reports": [ \
        {"value": 110000,"date": "2016-08-23"}, \
        {"value": 121000, "date": "2016-08-16"}, \
        {"value": 133100, "date": "2016-08-09"}, \
        {"value": 146410, "date": "2016-08-02"}]}' \ 
https://app.usenotion.com/api/v1/batch_report 

The server will respond with a status of 201 Created and the following body:

{ "errors": [], "status": "created" } 

If there are any errors processing your request, the server will return a 400 Bad Request and the errors will appear in the errors list.