返回首页

NutriSpec Public API v1

The NutriSpec API generates FDA, CFIA, EU, and China nutrition labels programmatically via a RESTful JSON API with API key auth — embed labels, automate batch exports, and integrate with your ERP or recipe system.

Generate nutrition labels programmatically. RESTful JSON API with API key authentication.

Authentication

All API requests require an API key passed in the x-api-key header.

curl -H "x-api-key: nspec_xxxxxxxxxxxx" \
  https://nutrispec.ai/api/v1/label \
  -H "Content-Type: application/json" \
  -d '{"recipe":{...}}'

Get your API key from Dashboard → API Keys. Rate limits: Free 30/min, Pro 100/min, Team 300/min.

POST/api/v1/label

Generate a nutrition label from a recipe.

REQUEST BODY

{
  "recipe": {
    "name": "Chocolate Chip Cookies",
    "yieldFactor": 0.9,
    "servingSizeGrams": 30,
    "servingsPerContainer": 24,
    "ingredients": [
      {
        "name": "Wheat flour",
        "weightGrams": 280,
        "nutrients": {
          "energy_kcal": 364,
          "total_fat": 1.0,
          "protein": 10.3,
          ...
        }
      }
    ]
  },
  "regulation": "fda"
}

RESPONSE

{
  "code": 0,
  "data": {
    "label": { "servingSize": "30g", "nutrients": [...] },
    "allergens": { "detected": [...], "declaration": "Contains: ..." },
    "claims": [...],
    "healthClaims": [...],
    "structureFunctionClaims": [...]
  }
}
GET/api/v1/recipes

List all saved recipes for the authenticated user.

RESPONSE

{
  "code": 0,
  "data": [
    { "id": "rec_...", "name": "Cookies", "servingSizeGrams": 30, ... }
  ]
}
POST/api/v1/recipes

Create or update a saved recipe.

REQUEST BODY

{
  "name": "My Recipe",
  "recipe": {
    "servingSizeGrams": 30,
    "servingsPerContainer": 12,
    "yieldFactor": 0.9,
    "ingredients": [...]
  }
}

RESPONSE

{ "code": 0, "data": { "id": "rec_...", "name": "My Recipe" } }
GET/api/v1/ingredients/search?q=flour

Search the USDA ingredient database (13,000+ foods).

RESPONSE

{
  "code": 0,
  "data": {
    "local": [...], "golden": [...], "usda": [...]
  }
}
GET/api/v1/units/convert?value=250&from=g&to=oz

Convert between US customary and metric units.

RESPONSE

{
  "code": 0,
  "data": { "originalAmount": 250, "originalUnit": "g", "convertedAmount": 8.82, "convertedUnit": "oz" }
}
POST/api/v1/label/export?format=csv

Export label data in CSV format for spreadsheet analysis.

RESPONSE

Content-Type: text/csv
Nutrient,Value,Unit,%DV
Calories,180,kcal,-
Total Fat,12,g,15%
...
Webhooks

Configure webhook URLs to receive label data automatically when a label is generated:

POST /api/v1/webhooks/configure
{
  "url": "https://your-app.com/webhook/nutrispec",
  "events": ["label.generated", "label.updated"],
  "secret": "your-webhook-signing-secret"
}

Webhook payloads are signed with HMAC-SHA256. Verify using the x-nutrispec-signature header.

SDK Examples

JavaScript / TypeScript

const res = await fetch("https://nutrispec.ai/api/v1/label", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.NUTRISPEC_API_KEY,
  },
  body: JSON.stringify({ recipe: { ... }, regulation: "fda" }),
});
const { data } = await res.json();
console.log(data.label.nutrients);

Python

import requests
res = requests.post(
    "https://nutrispec.ai/api/v1/label",
    headers={"x-api-key": "nspec_xxxx", "Content-Type": "application/json"},
    json={"recipe": {...}, "regulation": "fda"},
)
label = res.json()["data"]["label"]