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).

Definition

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.

Summary of resource URL patterns

/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.

Example request

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.

Example response

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.

Definition: script tag

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

Alternative: iframe

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

Label exports Available now

SVG / PNG / PDF rendered server-side by the same engine as the app, with plan rules (formats, file types, watermark) enforced at the door. Call it directly with your session token until API keys reach general availability. Returns the binary file, or 403 outside your plan.

Two notes on parity with in-app export. The app renders in the browser, so use this endpoint when you need a label produced without one. And jpg currently returns PNG bytes, while eps and ai are export-only formats the endpoint does not serve.

Definition

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.

Definition

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

Example response

{
  "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).

Definition

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

Example request

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.

Example request

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.

Example response

{
  "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 support@nutritionfactlabel.com 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