AI / LLM Friendly Docs

This is a comprehensive single-file reference for the Nutrition AI Platform, optimized for LLMs, AI agents, chatbots, and RAG systems. For the full documentation with interactive OpenAPI specs, see https://passio.gitbook.io/nutrition-ai.

---

1. What is Nutrition AI?

Passio's Nutrition AI Platform provides AI-powered food recognition, a 2.5M+ food database, and nutrition analysis. Available via:

• REST API for web and backend development

• Mobile SDKs for iOS (Swift/SwiftUI), Android (Kotlin), React Native, and Flutter

• Easy AI - no-code platform for custom AI tools, chatbots, RAG, function chains

One Nutrition AI key works across the REST API and all SDKs. Easy AI uses a separate API key, available on the Easy AI platform.

---

2. Authentication

Step 1: Get your API key from https://accounts.passiolife.com

Step 2: Exchange it for a Bearer token (valid ~24 hours):

POST https://api.passiolife.com/v2/token-cache/unified/oauth/token/{YOUR_API_KEY}

Response:

{
  "access_token": "eyJhbGciOiJS...",
  "scope": "read:search read:products",
  "expires_in": 86155,
  "token_type": "Bearer",
  "customer_id": "0d8bb889-36e1-11ee-b9e9-92e504c243a4"
}

Step 3: Include on every request:

Authorization: Bearer <access_token>
Passio-ID: <customer_id>
Content-Type: application/json

Cache the token and refresh before expires_in elapses. On 401, re-authenticate.

---

3. API Base URL and Path Prefixes

Base URL: https://api.passiolife.com/v2/products

Prefix	Use
/napi/...	Recommended. Current production path for all REST API calls.
/food/...	Legacy path. Still functional but may not support all newer features.
/sdk/...	Internal SDK use only. Do not call directly from REST API.

All endpoint paths in this document use the /napi/ prefix.

---

4. Pricing and Token System

Tier	Monthly	Included tokens	Refill per 1M	Easy AI	Insights	AI Insights	Model switching
Starter	$99	1M	$25	Yes	No	No	No
Growth	$599	5M	$10	Yes	Yes	No	Yes
Pro	$2,999	100M	$2.50	Yes	Yes	Yes	Yes

Token cap for the billing period: cap = (included_monthly_tokens + refill_tokens_this_cycle) x 1,000,000

Up to 10% over this cap is allowed (grace period) before requests are rejected with HTTP 429.

Auto-refill can be enabled in account settings. Manual refills available via Manage Plan.

---

5. Core Endpoints - Food Database

Semantic search (AI-powered)

GET /napi/food/search/semantic?term=grilled+chicken+breast&limit=50

Returns: { results: [...], alternateNames: [...] }. Each result has displayName, refCode, nutritionPreview (calories, macros for default serving).

Advanced search (legacy)

GET /napi/food/search/advanced?term=Kirkland+chicken+breast&limit=50

Same response format. Legacy endpoint, still available for exact brand name and product searches. Use semantic search as the default.

Full nutrition by refCode

GET /napi/food/search/result/refCode/{refCode}

Returns a complete food item with all ingredients, nutrients (per 100g), portions, serving sizes, and brand info. This is the main endpoint for detailed nutrition data after search or recognition.

Barcode / UPC lookup

GET /napi/food/productCode/{barcode}

Example: GET /napi/food/productCode/0602652257230

Returns full food item if found; empty or 404 if barcode not in database.

---

6. Core Endpoints - Vision (Image Recognition)

Food recognition (default vision endpoint)

POST /napi/tools/vision/extractIngredientsAutoTyped

Handles food photos, barcode images, and nutrition labels in a single call. Recommended image size: 500px (maintaining aspect ratio).

JSON input (recommended):

{"image": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."}

Multipart input: form field name image for images, video_file for videos.

Response (array of recognized items):

[
  {
    "ingredientName": "Grilled Chicken Breast",
    "portionSize": "1 breast",
    "weightGrams": 174,
    "nutritionPreview": {
      "calories": 284,
      "protein": 53,
      "fat": 6,
      "carbs": 0,
      "servingWeight": 174
    },
    "refCode": "eyJ..."
  }
]

• ingredientName, portionSize, weightGrams = AI's raw recognition output

• nutritionPreview = pre-calculated from Passio's nutrition database (use for display)

• refCode = fetch full details via /napi/food/search/result/refCode/{refCode}

Nutrition label scan

POST /napi/tools/vision/extractPackagedProduct

Extracts serving size, calories, macros, micronutrients, ingredients list from nutrition facts labels. Recommended image size: 1200px.

Same input format as food recognition (base64 JSON or multipart image).

---

7. Core Endpoints - Text and Voice

Voice / text meal logging

POST /napi/tools/extractMealLogAction
Content-Type: application/json

{"content": "I had two eggs and a slice of whole wheat toast with butter for breakfast"}

Also accepts audio_file via multipart for voice input.

Response (array of log actions):

[
  {
    "ingredientName": "Eggs",
    "portionSize": "2 large",
    "nutritionPreview": {"calories": 156, "protein": 12, "fat": 11, "carbs": 1, "servingWeight": 100},
    "refCode": "eyJ..."
  },
  {
    "ingredientName": "Whole wheat bread",
    "portionSize": "1 slice",
    "nutritionPreview": {"calories": 81, "protein": 4, "fat": 1, "carbs": 14, "servingWeight": 28},
    "refCode": "eyJ..."
  }
]

Extract ingredients from text

POST /napi/tools/extractIngredients
{"content": "2 cups flour, 3 eggs, 1 cup milk, pinch of salt"}

Returns array of ingredient objects with name, portion, quantity, weight, and Passio database matches.

Group ingredients to meal

POST /napi/tools/groupIngredientsToMeal
{"content": "...flat ingredient list..."}

Groups a flat ingredient list into logical meal components.

Other text tools

Endpoint	Purpose
POST /napi/tools/visualAlternativeSuggestions	Visually similar food alternatives for dietary preferences
POST /napi/tools/invisibleIngredientSuggestions	Hidden ingredients (sugar in coffee, oil in dressing)
POST /napi/tools/possibleIngredientSuggestions	Likely ingredients for a given food/meal
POST /napi/tools/predictIngredients	Predict constituent ingredients for dietary analysis

All text tools accept {"content": "..."} as JSON body. Many also accept audio_file via multipart.

---

8. Meal Plans

Two-step workflow

1. Preview (fast, 4-20 seconds): POST /napi/tools/generateMealPlanPreview

2. User reviews, rejects meals (rejected: true), re-sends for regeneration

3. Full generation (1.5-6 minutes): POST /napi/tools/generateMealPlan

Input: {"content": "Generate a 3 day meal plan with high protein for a 33 year old athletic male"}

Optional query params: model (idea generation), model2 (day refinement). Using gemini-2-5-pro for both improves quality but costs more.

Preview response:

[
  {
    "day": 1,
    "meals": [
      {"mealName": "Protein Pancakes", "rejected": false},
      {"mealName": "Tuna Wrap", "rejected": false},
      {"mealName": "Chicken Stir Fry", "rejected": false}
    ]
  }
]

Additional meal plan endpoints

Endpoint	Purpose
POST /napi/tools/regenerateMeals	Regenerate specific meals from existing plan
POST /napi/tools/updateMealPlanShoppingList	Regenerate shopping list for plan
POST /napi/tools/humanizeShoppingList	Convert technical list to shopping format
POST /napi/affiliates/convertMealPlanToAffiliateLink	Generate Instacart/affiliate link

---

9. Rating and Analysis Endpoints

Endpoint	Purpose	Returns
POST /napi/tools/ultraProcessedFoodRating	UPF rating (1-10)	{rating, highlightedIngredients, chainOfThought}
POST /napi/tools/genericFoodRating	Custom criteria food rating	{rating, chainOfThought}
POST /napi/tools/estimateGlycemicIndexLoad	Glycemic index and load	{ingredients: [{gi_low, gi_high, gl_low, gl_high, confidence}]}

All accept {"content": "..."}.

---

10. Intelligence Profile (Personalization)

Generate a dietary profile from user info, then pass it as a header for personalized results.

Generate: POST /napi/tools/generateIntelligenceProfile

{"content": "I am vegan with high blood pressure and want to lose weight"}

Response:

{
  "headerKey": "<encoded-profile-string>",
  "decodedProfile": {
    "dietaryRestrictions": ["vegan"],
    "allergies": [],
    "healthConditions": ["high blood pressure"],
    "goals": ["weight loss"]
  }
}

Use: Pass Passio-Intelligence-Profile: <headerKey> on subsequent requests to extractMealLogAction, nutritionAdvisor, generateMealPlan, extractIngredients, and other AI tools.

---

11. Food Submission and Reporting

Endpoint	Purpose
POST /napi/food/submit/product	Submit a new food product to the database
POST /napi/food/report/product	Report inaccurate data for an existing product

---

12. Nutrition Data Model

Nutrients per 100g

All nutrients are stored assuming a 100g reference weight. To calculate nutrients for a specific serving:

N = nutrient_amount * (portion_weight_grams / 100) * quantity

Portions and serving sizes

Each food item has an array of portions. The first (default) portion is recommended. If no portions exist, assume 100g:

{"name": "100g", "quantity": 1, "suggestedQuantity": [1], "weight": {"unit": "g", "value": 100}}

A typical portion:

{"name": "tbsp", "quantity": 1, "suggestedQuantity": [1], "weight": {"unit": "g", "value": 17}}

Food item structure

A food item returned by refCode lookup:

{
  "name": "Example Food",
  "displayName": "Example Food",
  "ingredients": [
    {
      "id": "...",
      "name": "EXAMPLE FOOD",
      "metadata": {
        "nutrients_reference": {
          "calories": {"value": 294, "unit": "kcal"},
          "protein": {"value": 25, "unit": "g"},
          "fat": {"value": 12, "unit": "g"},
          "carbs": {"value": 30, "unit": "g"}
        },
        "serving_sizes": [
          {"quantity": 1, "unitName": "serving", "weightGrams": 85}
        ]
      }
    }
  ]
}

For recipes (multiple ingredients), calculate each ingredient's nutrients separately, then sum. Apply the top-level portion to the combined total.

nutritionPreview vs full details

• nutritionPreview (on search/recognition results): pre-calculated calories and macros for the default serving. Use for quick display.

• Full details via refCode: complete nutrient profile (20-30 nutrients), all available portions, ingredient breakdown, brand info.

refCode

Base64-URL-encoded JSON containing lookup info. Returned by search results and recognition responses. Stable for persistent storage. Use with GET /napi/food/search/result/refCode/{refCode}.

---

13. Localization

Translation

Localization-ISO: ja

ISO 639-1 code. Translates food names, descriptions, serving sizes in responses.

Regional optimization (does NOT translate)

Passio-Product-Localization: {"targetLanguage":"ja-JP"}

BCP47 tag or ISO 639-1. Activates region-specific search indexes and optimizes AI responses for that region. Does not translate - use Localization-ISO for translation.

These are independent - use one or both. For a fully localized experience, set both.

Search filtering

Passio-Search-Config: {"regionFilters":{"jp":1},"strictRegionMode":true,"typeFilters":["branded"]}

Field	Type	Description
regionFilters	{code: priority}	Boost/restrict by region. Priority 1 = highest. Codes: ISO2, BCP47, or language.
sourceFilters	string[]	Filter by source: fdc, firebase, legacy, openfood, passio, passio-foodai
typeFilters	string[]	Filter by type: generic, branded, recipe
strictRegionMode	boolean	true = only matching regions; false (default) = boost
ignoreWithConcernFlags	number[]	Exclude items with data quality issues (e.g. 1002=missing nutrients, 1100=invalid serving)
dataSourceConfigs	object[]	Control databases and result counts

SDK localization methods

SDK Method	Header	Input
updateLanguage(languageCode:)	Localization-ISO	ISO 639-1 ("ja"). Translates responses.
updateProductLocalization(localizationCode:)	Passio-Product-Localization	BCP47 or ISO 639-1 ("ja-JP"). Regional optimization, does NOT translate.
updateSearchConfiguration(config:)	Passio-Search-Config	JSON string

---

14. Image Input Details

JSON (recommended)

{"image": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."}

The data:image/jpeg;base64, prefix is required. Missing it causes 400 errors.

Multipart form data

Use image as the form field name for image uploads and video_file for video uploads.

Recommended sizes

• Food recognition: 500px (maintaining aspect ratio)

• Nutrition label scan: 1200px (maintaining aspect ratio)

---

15. Token Usage Tracking

Response headers (on every API response)

Header	Description
X-Budget-Cap	Total token budget for billing period
X-Period-Usage	Tokens used this period
X-Request-Usage	Tokens used by this request
X-Model-Tag	AI model used for this request
X-Estimated-Cost-Usd	Your total cost for this request (USD)
X-Wholesale-Cost-Usd	Raw AI provider cost for this request (USD)
X-Billed-Tokens-Total	Total billed tokens (input + output, after normalization)
X-Billed-Input-Tokens	Billed input tokens (after normalization)
X-Billed-Output-Tokens	Billed output tokens (after normalization)

SDK token tracking

Use PassioAccountListener (Android/RN/Flutter) or PassioAccountDelegate (iOS). Fires on each request with PassioTokenBudget:

• requestUsage (iOS/RN) or tokensUsed (Android/Flutter) - tokens consumed by the request

• budgetCap - total cap

• periodUsage - cumulative usage this period

• usedPercent - percentage of cap consumed (property on iOS/RN, method on Android/Flutter)

• apiName - which API was called

Note: The SDK callback only surfaces X-Budget-Cap, X-Period-Usage, and X-Request-Usage. Cost and billed-token headers are not exposed — use the REST API or accounts dashboard for those.

Dashboard

https://accounts.passiolife.com - usage breakdown by route type, refill settings, projected usage.

---

16. Model Settings

Query parameter model on any AI endpoint overrides the default model. Growth/Pro users can set a default model in the accounts dashboard. Priority order:

1. model query parameter (highest)

2. Dashboard default (Growth/Pro)

3. System default

---

17. Mobile SDKs

Platforms

iOS (Swift/SwiftUI, CocoaPods or SPM), Android (Kotlin, Gradle), React Native (npm), Flutter (pub).

Configuration

All SDKs use remoteOnly = true by default (recommended - no model downloads needed):

passioConfig.key = "YOUR_API_KEY"
passioConfig.remoteOnly = true

Key SDK methods mapping to REST API

SDK Method	REST API Endpoint
recognizeImageRemote(image:)	POST /napi/tools/vision/extractIngredientsAutoTyped
recognizeNutritionFactsRemote(image:)	POST /napi/tools/vision/extractPackagedProduct
searchForFood(byText:)	GET /napi/food/search/advanced
searchForFoodSemantic(byText:)	GET /napi/food/search/semantic
recognizeSpeechRemote(text:)	POST /napi/tools/extractMealLogAction
fetchFoodItemForRefCode(refCode:)	GET /napi/food/search/result/refCode/{refCode}
fetchFoodItemForProductCode(code:)	GET /napi/food/productCode/{code}

SDK data model

• PassioAdvisorFoodInfo - recognition result with ingredientName, portionSize, weightGrams (AI estimate), nutritionPreview, foodDataInfo

• PassioFoodItem - full food item with name, ingredients[], amount (portions/servings)

• PassioFoodAmount - selected serving unit and quantity, weightGrams() (calculated from serving), nutrientsSelectedSize(), nutrientsReference() (per 100g)

• PassioIngredient - single ingredient with metadata containing nutrients and portions

Changing serving sizes (SDK)

foodItem.amount.selectedUnit = "slice"
foodItem.amount.selectedQuantity = 2
let nutrients = foodItem.amount.nutrientsSelectedSize()

---

18. Common Errors

Code	Cause	Fix
400	Malformed request. Common: missing data:image/...;base64, prefix, wrong Content-Type	Check request format
401	Missing or expired Bearer token	Re-authenticate (tokens last ~24h)
403	Invalid API key or insufficient permissions	Verify key at accounts portal
429	Token cap exceeded (with grace period exhausted)	Check X-Period-Usage header, refill or wait for next billing period
500	Server error	Retry with exponential backoff

Retry guidance: 401 = re-auth then retry once. 429 = exponential backoff (1s, 2s, 4s). 500 = exponential backoff.

---

19. Deprecated Features

REST API

Legacy	Replacement
Advisor threads (/nutrition-advisor/threads/...)	POST /napi/tools/nutritionAdvisor
Pre-built meal plans (/food/recommend/mealPlans)	generateMealPlan / generateMealPlanPreview
extractFoodAndIngredients	extractIngredientsAutoTyped (meal hierarchy now default)

SDK

Legacy	Replacement
startFoodDetection / stopFoodDetection	recognizeImageRemote
recognizeImageRemoteWithGrouping	recognizeImageRemote (hierarchy now default)
startNutritionFactsDetection / stopNutritionFactsDetection	recognizeNutritionFactsRemote
fetchMealPlans / fetchMealPlanForDay	generateMealPlan / generateMealPlanPreview
Advisor (initConversation, sendMessage, sendImage)	Pending migration to tools endpoint

---

20. Easy AI

No-code platform for building custom AI tools, chatbots, RAG systems, and function chains. Access via the accounts portal or easyai.passiolife.com.

• Web / server-side: Use the code snippets provided on the Easy AI platform to call your endpoints directly. A separate Easy AI API key is available on the Easy AI webpage for authentication — no need to route through the Nutrition AI API.

• Mobile SDKs: Easy AI access from within the SDK is currently in development.

---

21. Data Sources and Licensing

The database includes data from:

• USDA FDC - US government food composition data

• Open Food Facts - Community-sourced product data (ODbL 1.0 license, attribution required)

• Passio-curated data - internally researched and maintained

When displaying data from Open Food Facts, attribution is required per the ODbL 1.0 license.

---

22. Additional Resources

• OpenAPI interactive docs: https://api.passiolife.com/v2/products/napi/docs

• OpenAPI spec JSON: https://cdn.passiolife.com/documentation/openapi_manual.json

• Accounts portal: https://accounts.passiolife.com

• Support: [e-mail]

• Slack community: https://passio-community.slack.com/channels/help

• Full documentation: https://passio.gitbook.io/nutrition-ai