Alacalc API documentation

This document provides API information for connecting to the Alacalc Nutritional Information system.

In order to use this API, you need to create an API key from your user account.

Example usage

Creating a new session

The first step is to to authenticate and store the session information in a cookie. Once you have obtained the login-email and the API key from your account, the session is created with:

curl -c alacalc_cookie --data "[email protected]&api_access_key=APIKEY"

Obtain list of all recipes

We can use the API to retrieve information from the alacalc system. For example to obtain a list of all recipes, we use:

curl -b alacalc_cookie

Retrieve allergen and nutritional information of a recipe

We can retrieve the allergen and nutritional information of the recipe with id=123 with:

curl -b alacalc_cookie ",nutrition"

Download a food label

Finally, we can download the food label with

curl -b alacalc_cookie -o label.svg ""

Create a new recipe

A new recipe is created by making a post request, for instance with

curl --header "Content-Type: application/json" --request POST -b alacalc_cookie --data '{"recipes":{"name":"My new recipe","quantity_per_serving":100,"weight_loss":0}}'

Create a new user

A new user can be created with:

curl --header "Content-Type: application/json" --request POST --data '{"email":"[email protected]","password":"mysecret"}'

The return value contains the user's API key, which can be used to create a new user sessions.

Update a user

The information of a user can be updated with (note that you need a session cookie here):

curl --header "Content-Type: application/json" --request PUT -b alacalc_cookie --data '{"firstname":"Simon"}'


Ingredient items

Resource Description
GET /api/v1/recipes/:recipe_id/ingredient_items Show a recipe's ingredient items
POST /api/v1/recipes/:recipe_id/ingredient_items Add an ingredient items to a recipe
PUT /api/v1/recipes/:recipe_id/ingredient_items/:id Update an ingredient items associated with a recipe
DELETE /api/v1/recipes/:recipe_id/ingredient_items/:id Delete an ingredient items associated with a recipe


Resource Description
GET /api/v1/ingredients/:id Show an ingredient
POST /api/v1/ingredients Create an ingredient
PUT /api/v1/ingredients Update a recipe
GET /api/v1/ingredients/search Search ingredients


Resource Description
GET /api/v1/recipes List recipes (most recent first)
GET /api/v1/recipes/:id Show a recipe
GET /api/v1/recipes/:id/allergens Deprecated: use recipes/:id?include=allergens instead.
GET /api/v1/recipes/:id/label.[:format] Get a label
GET /api/v1/recipes/:id/declaration_names Get the declaration names as HTML.
POST /api/v1/recipes Create a recipe
PUT /api/v1/recipes/parse Parse a recipe from a string
PUT /api/v1/recipes/:id Update a recipe


Resource Description
POST /api/v1/sessions Create a user session using a POST request (recommended)
GET /api/v1/sessions/create_via_get Create a user session with a GET request (mostly for auto-login purposes)
DELETE /api/v1/sessions Destroys a user session


Resource Description
POST /api/v1/users Create a user (optionally associated with a parent account) and returns the user's API key.
PUT /api/v1/users Update the user information.
GET /api/v1/users/show_usage Gives an overview of the account usage (e.g. number and detailed information about the created recipes during the period) over a specific time-period. If the account is a parent account then same summary is given for all child accounts.


Resource Description
GET /api/v1/ingredients/:ingredient_id/weights Show the weight units of an ingredient
POST /api/v1/ingredients/:ingredient_id/weights Add a weight unit to an ingredient
PUT /api/v1/ingredients/:ingredient_id/weights/:id Update a weight unit of an ingredient
DELETE /api/v1/ingredients/:ingredient_id/weights/:id Delete a weight unit associated with an ingredient