NFL API Documentation

Render compliant nutrition labels, manage recipes and pull nutrition data programmatically. Two things work today for every account that qualifies: the live label embed and server-rendered exports. The REST resource API is in early access on the Business plan.

The API only accepts and returns JSON (label render endpoints return the binary file).

https://nutritionfactlabel.com/api/v1

API endpoint

All REST resources live under one versioned base URL. Breaking changes only ever ship under a new version prefix. During early access your welcome email confirms the base URL active for your keys.

/v1/recipes
/v1/recipes/{RECIPE_ID}
/v1/recipes/{RECIPE_ID}/label.{svg|png|pdf}
/v1/ingredients
/v1/ingredients/{INGREDIENT_ID}
/v1/analyze

Authentication

Authenticate every request with your secret key in the Authorization header. Keys are scoped to your account and carry your plan's entitlements: the same server-side gates as the app.

Keep keys secret. Never ship them in client-side code; proxy through your backend. Rotate a leaked key immediately via support.

curl https://nutritionfactlabel.com/api/v1/recipes \
  -H 'Authorization: Bearer nfl_live_9f30c2...'

Rate limits

To keep things fair and stable: 60 requests per minute per key; label renders additionally capped at 5 concurrent; request bodies at 1 MB. Beyond a limit you get 429 with a Retry-After header.

HTTP/2 429 Too Many Requests
Retry-After: 22

{ "error": { "code": "rate_limited",
  "message": "Try again in 22 seconds." } }

Live label embed Available now

Show an always-current label on any website, no API key. Enable the embed on a recipe in the Generator (recipe row → Embed) to get its public token.

The script tag auto-sizes its height; update the recipe in NFL and every page showing the embed updates. Professional and Business plans; disabling the embed kills the token immediately.

<script src="https://nutritionfactlabel.com/embed.js"
        data-label="YOUR_EMBED_TOKEN"
        data-width="290"></script>

<iframe
  src="https://nutritionfactlabel.com/embed/TOKEN"
  width="290" height="560" frameborder="0"
  title="Nutrition Facts"></iframe>

Label exports Available now

SVG / PNG / JPG / PDF rendered server-side by the same engine as the app, with plan rules (formats, file types, watermark) enforced at the door. In-app exports use this automatically; direct calls authenticate with your session token until API keys reach general availability. Returns the binary file, or 403 outside your plan.

POST /functions/v1/export-label
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "fileType": "pdf",
  "data": { ...label state },
  "extra": { }
}

Recipes Early access · Business

The core object: ingredients, servings and a label_format (152 formats across 114 countries) produce the computed label: nutrients rounded per jurisdiction, ingredient statement, allergens.

Key attributes: id, name, servings, serving_weight_g, label_format, label (computed), embed_enabled, timestamps.

GET    /v1/recipes
POST   /v1/recipes
GET    /v1/recipes/{ID}
PUT    /v1/recipes/{ID}
DELETE /v1/recipes/{ID}
GET    /v1/recipes/{ID}/label.pdf

{
  "id": "rcp_2m4k9q",
  "name": "Chocolate Chip Cookies",
  "servings": 12,
  "serving_weight_g": 28,
  "label_format": "standard",
  "label": {
    "calories": 140,
    "total_fat_g": 7,
    "allergens": ["wheat","milk","soy"],
    ...
  },
  "embed_enabled": false
}

Ingredients Early access · Business

Custom ingredients with per-100 g nutrition, allergen species and optional costing, identical to ones created in the app, searchable in the Generator. USDA ingredients address as usda:{fdc_id}; set "archived": true to archive (excluded from lists by default).

GET    /v1/ingredients
POST   /v1/ingredients
GET    /v1/ingredients/{ID}
PUT    /v1/ingredients/{ID}
DELETE /v1/ingredients/{ID}

POST /v1/ingredients

{
  "name": "Organic almond flour",
  "nutrients_per_100g": {
    "calories": 571, "total_fat_g": 50,
    "protein_g": 21, "dietary_fiber_g": 10
  },
  "allergens": ["tree_nuts"],
  "cost_per_unit": 12.5, "unit": "kg"
}

Nutrition analysis Early access · Business

One-shot analysis without saving a recipe. Returns the same label object plus claims: the nutrient-content claims the values qualify for (e.g. "good source of fiber") with their CFR citations. Unmatched names are matched against USDA.

POST /v1/analyze

{
  "label_format": "standard",
  "servings": 12,
  "serving_weight_g": 28,
  "ingredients": [
    { "ingredient_id": "usda:173410", "grams": 120 },
    { "name": "brown sugar", "grams": 80 }
  ]
}

Errors

Conventional HTTP codes; error bodies are JSON with a stable machine code and human message. 400 malformed input · 401 bad key · 403 outside your plan · 404 not found / not yours · 429 rate limited · 500 retry with backoff.

{
  "error": {
    "code": "plan_format_not_allowed",
    "message": "The 'eu-1169' label format
      requires the Professional plan."
  }
}

Getting access

The embed needs no key; enable it per recipe (Professional+). REST API early access is included in the Business plan: email [email protected] from your account email and keys are provisioned within one business day.

Missing an endpoint you need? Tell us. Early-access partners steer the roadmap.

Upgrade to Business