Requests

Rules that apply to every request: query parameters, languages, IDs, format, connection and size limits.

Query Parameters

These parameters can be added to most endpoints to control the response.

full-resource

Value	Default	Description
true	No	Returns complete JSON response with all fields
false	Yes	Returns minimal response (saves bandwidth)

When to use: Set full-resource=true when you need all calculated values. Use false (default) for faster responses when you only need the core metrics (rating, co2-value).

Fields included only with full-resource=true:

• Detailed ingredient breakdowns
• All nutrient values
• Improvement percentages
• Reduction values

indicators

Value	Default	Description
true	No	Includes VitaScore and environmental indicators
false	Yes	Excludes additional indicators

When to use: Set indicators=true when you need nutritional scoring (VitaScore) or environmental metrics (water footprint, rainforest, animal welfare, seasonality, local sourcing).

Additional fields when indicators=true:

• vita-score-points, vita-score-rating, vita-score-award
• water-footprint-rating, scarce-water-liters
• rainforest-label, rainforest-rating
• animal-treatment-label, animal-treatment-rating
• season-label, season-rating
• local-label, local-rating

nutrient-values

Value	Default	Description
true	No	Includes nutrient-values-estimated-per-specified-amount for each ingredient
false	Yes	Excludes nutrient value estimates

ingredients-declaration

Value	Default	Description
true	No	Includes parsed ingredients-declaration data for each ingredient
false	Yes	Excludes ingredient declaration data

return-uids

Value	Default	Description
true	No	Includes internal uid fields in response for recipes and ingredients
false	Yes	Excludes internal UIDs

transient (query parameter)

Value	Default	Description
true	No	Every recipe in the request is transient: calculated and returned, but not kept and not counted in reports
false	Yes	Recipes are kept and counted, unless a batch item sets "transient": true

The body field on a batch item has the same meaning for that one recipe. See Transient Recipes.

Localization

The API is designed such that one request may contain information about an object (e.g. a recipe or a supply) in multiple languages. Every JSON field which is subject to localization has a language array as value:

{
  "language": "de",
  "value": "Kürbisrisotto"
}

The language field must contain one of the ISO 639-1 alpha-2 codes.

ID Generation

The IDs of recipes, kitchens and supplies can be generated in two different ways:

1. POST request: ID is generated by Eaternity
2. PUT request: You provide your own ID in the URL (recommended)

The ID can be any alphanumeric value following this regex pattern: [-a-zA-Z0-9+&@#/%?=~_|!:,.;]*[-a-zA-Z0-9+&@#/%=~_|]

Format

• The API accepts JSON in requests and returns JSON in all responses
• Only UTF-8 character encoding is supported
• All requests must be encrypted through SSL

SSL & Server Name Indication (SNI)

Since Eaternity uses distributed servers, the IP-address of the service changes and is shared between different applications. To make SSL work, the desired hostname (co2.eaternity.ch) needs to be specified with every request according to the SNI specification:

openssl s_client -connect co2.eaternity.ch:443 -servername co2.eaternity.ch

We recommend whitelisting the Cloudflare root certificate cloudflare_origin_rsa.pem.

Request Size Limits

Recipe and supply endpoints are subject to two kinds of size limits:

• Soft limits — these limits should not be exceeded by requests; larger requests might fail or be rejected. The request is still processed, but on a best-effort basis.
• Hard limits — the request (or, on batch routes, the individual item) is rejected with 413 Payload Too Large.

Recipes

Description	Applies to	Soft Limit
Ingredients per recipe (direct count)	Single-recipe routes, and each item in a recipe batch	100
Ingredients per recipe, including sub-recipes (recursive count)	Recipe batch only	150
Recipes per batch request	Recipe batch	100

Supplies

Description	Applies to	Soft Limit
Ingredients per supply (direct count)	Single-supply routes that wait for a result	100
Supplies per batch request	Supply batch	5000
Ingredients of all supplies in a batch request (direct count)	Supply batch	10000