API FAQ
Frequently asked questions for the REST API
Authentication
How do I get my Nutrition AI key?
Sign in at accounts.passiolife.com and go to Product Details. Your Nutrition AI key is on the Account Info tab.
Do I use the Nutrition AI key directly in requests?
No. Exchange it for a Bearer token via POST /v2/token-cache/unified/oauth/token/{key}, then use Authorization: Bearer <token> and Passio-ID: <customer_id> on every request. See Authorization Setup.
How long does the token last?
About 24 hours. Cache the expires_in value from the token response and refresh before it elapses. On 401, re-authenticate and retry.
Food Lookup and Search
How do I search for food by name?
Use GET /napi/food/search/semantic?term=chicken (recommended). This is the primary search endpoint — AI-powered and best for natural-language queries. The legacy GET /napi/food/search/advanced?term=... is still available for exact brand/product name matching. See Search Routes.
How do I look up a product by barcode?
GET /napi/food/productCode/{barcode} with your Bearer token. See Barcode Scanning.
How do I get full nutrition details for a food?
Use the refCode returned by search or recognition: GET /napi/food/search/result/refCode/{refCode}. See Food Details.
What is a refCode?
A base64-URL-encoded reference string returned in search results and recognition responses. Use it with the food details endpoint to fetch complete nutrition data. It is stable and safe for persistent storage.
Vision and Image Recognition
How do I recognize food from a photo?
POST /napi/tools/vision/extractIngredientsAutoTyped - this handles food photos, barcode images, and nutrition labels in a single call. Send the image as a base64 data URI in JSON (recommended) or as multipart with field name image. See Image Recognition.
How do I extract nutrition from a label photo?
POST /napi/tools/vision/extractPackagedProduct - specifically for nutrition facts label images. Recommended image size is 1200px. See Nutrition Facts Scan.
I'm getting a 400 "Failed to get tool and prompt" error. What's wrong?
The image was not received correctly. Common causes:
Missing the data URI prefix. Send as
data:image/jpeg;base64,<base64_string>, not raw base64.Missing or malformed image data.
To create a correct data URI from a file:
What image size should I use?
500px (maintaining aspect ratio) for food recognition. 1200px for nutrition label scanning.
Voice and Text
How do I log food from voice or text?
POST /napi/tools/extractMealLogAction with {"content": "I had two eggs and toast"} or send an audio_file via multipart. See Voice Logging.
Do AI tools support voice/audio input?
Yes. Many tools (extractMealLogAction, extractIngredients, nutritionAdvisor, generateMealPlan, etc.) accept audio_file via multipart in addition to JSON content.
Meal Plans and AI Tools
How do I generate a meal plan?
Use the two-step workflow: POST /napi/tools/generateMealPlanPreview for a fast preview (4-20s), let the user review and reject meals, then POST /napi/tools/generateMealPlan for the full calculated plan (1.5-6 min). See Mealplans.
How do I personalize responses for dietary restrictions?
Call POST /napi/tools/generateIntelligenceProfile with the user's dietary info. Pass the returned headerKey as Passio-Intelligence-Profile header on subsequent requests. See Intelligence Profile.
How do I get nutrition advice or recipe suggestions?
POST /napi/tools/nutritionAdvisor with the user's question. Returns advice, recipes, and product suggestions.
Data and Nutrients
How are nutrients stored?
All nutrients are per 100g. To calculate for a serving: N = nutrient_amount * (portion_weight / 100) * quantity. See Nutritional Data Model.
What is nutritionPreview vs full details?
nutritionPreview is a quick summary (calories, macros, serving weight) on search and recognition results - use it for display. For the full nutrient profile, all portions, and ingredient breakdown, fetch via refCode. See Preview vs Full Details.
How do I report bad food data or submit new products?
POST /napi/food/report/product to report issues. POST /napi/food/submit/product to submit new food data. See Food Submission & Reports.
Billing and Usage
Where do I see usage and cost estimates?
Three places:
Account Info tab at accounts.passiolife.com - token usage, projected usage, pricing by route type.
Insights tab (Growth/Pro) - deeper route-level analytics and cost breakdowns.
API response headers -
X-Budget-Cap,X-Period-Usage,X-Request-Usage,X-Estimated-Cost-Usdon every response.
See Token System and Pricing and Track Token Usage.
What happens when I hit my token cap?
There is a 10% grace period. After that, requests return 429 until the next billing period or until you add a refill. See Errors and Troubleshooting.
Localization
How do I get translated food names?
Set the Localization-ISO header to a language code (e.g. ja for Japanese). BCP-47 tags like es-MX are also accepted but are normalized to the two-letter language code (es) — the region part is not used for translation. This translates food names, descriptions, and serving sizes.
How do I get region-specific search results?
Set the Passio-Product-Localization header (e.g. {"targetLanguage":"ja-JP"}). This routes queries to region-specific search indexes and adds regional context to AI prompts, but does not translate — use Localization-ISO for that. The full BCP-47 tag is preserved (the region part matters here).
How do I filter search results by region, source, or food type?
Set the Passio-Search-Config header with a JSON object to control post-query filtering: regionFilters to boost/restrict by region, sourceFilters for data source, typeFilters for food type, and strictRegionMode to exclude items without region data. This works alongside Passio-Product-Localization — the localization header routes to the right search index (pre-query), while Passio-Search-Config filters and re-ranks results (post-query).
See Localization for full details.
Last updated