Institutional-Grade Food & Nutrition Intelligence APIAPI Edge Operational · <20ms p95

FoodVivo REST API Documentation

FoodVivo provides institutional-grade nutritional intelligence across natural language text, plate photos, hybrid barcodes, and multi-photo nutrition labels with sub-second response times, zero-overhead portion scaling, and verified mathematical integrity.

Live Base URL:https://foodvivo-api.flappybird-assets.workers.dev

1Get Secret API Key

2Send Plate / Text / Barcode

Call /v1/food/analyze or /v1/food/barcode with JSON payload.

3Verified Macros Output

Receive USDA-calibrated macros with 4-4-9 caloric verification & allergen flags.

Authentication

Authenticate your requests by including your secret API key in the request headers. Both the standard Authorization: Bearer <KEY> header and the X-API-Key: <KEY> header are supported.

Authorization: Bearer sk_live_9f83a2...

Tier 0 Edge KV Cache (<18ms)

Identical meal queries and scanned barcodes are automatically cached in Cloudflare KV edge storage for 7 days, providing sub-20ms response latencies with $0.00 compute cost.

4-4-9 Mathematical Integrity

Every output is audited against caloric equations:Calories ≈ (4 × Protein) + (4 × Carbs) + (9 × Fat)Discrepancies exceeding ±10% are reconciled automatically.

Rate Limit & Standard Response Headers

Every HTTP response includes metadata headers to help your client application monitor usage, track latencies, and avoid rate limiting.

Header	Example	Description
X-RateLimit-Limit	600	The maximum allowed requests per minute (RPM) for your current plan tier.
X-RateLimit-Remaining	598	Number of remaining requests allowed in the current rolling 60-second window.
X-RateLimit-Reset	1724668800	Unix timestamp when the current rate limit window resets.
X-Request-Id	req_8f12a9c4	Unique request trace ID for debugging, logging, and submitting accuracy feedback.
X-Bypass-Cache	true	Optional request header to bypass Cloudflare KV cache and force fresh AI model analysis.

Plan Tiers & Quota Reference

Starter20 RPM200 req/mo

Hobby60 RPM4,000 req/mo

DeveloperUnlimited RPM22,500 req/mo

GrowthUnlimited RPM80,000 req/mo

ScaleDedicated SLACustom Tier

API Reference & Endpoints

Explore request bodies, definition schemas, and interactive code terminals for each endpoint.

Language:

POSTMultimodal Meal Analysis

/v1/food/analyze

Decompose natural language food descriptions, plate photos, or mixed restaurant meals into discrete ingredients with USDA-calibrated macros, FoodVivo neural grounding, and 4-4-9 caloric mathematical verification.

Try this in Interactive Playground

Headers

Authorization:Bearer sk_live_your_api_key

Content-Type:application/json

Body Parameters

textstringoptional

Natural language meal description (e.g. '2 scrambled eggs with avocado toast and coffee'). Required if image is not provided.

image_urlstringoptional

Public URL of a meal or plate photo for multimodal visual analysis.

image_base64stringoptional

Direct base64 data-URI string of the image (up to 10MB).

contextstringoptional

Optional meal context descriptor (e.g., 'Breakfast', 'Chipotle Post-Workout', 'Homemade Recipe').

Request (TYPESCRIPT)

const response = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/food/analyze", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "2 scrambled eggs with 1 slice sourdough toast and half avocado",
    context: "Breakfast",
  }),
});

const { data, meta } = await response.json();
console.log("Meal Title:", data.meal_title);
console.log("Totals:", data.totals);
console.log("Macro Split:", data.macro_split);

Response:

{
  "success": true,
  "data": {
    "meal_title": "Scrambled Eggs with Avocado Toast",
    "thought_process": "Identified 2 large scrambled eggs (cooked with minimal oil), 1 slice of artisanal sourdough toast, and 50g fresh Hass avocado. Grounded against USDA FoodData Central chemical assays with Atwater mathematical consistency.",
    "foods": [
      {
        "name": "Scrambled Eggs",
        "quantity": 2,
        "serving_size": 2,
        "serving_unit": "large eggs (100g)",
        "weight_g": 100,
        "calories": 144,
        "protein_g": 12.2,
        "carbs_g": 1.4,
        "fat_g": 9.8,
        "allergens": ["egg"],
        "dietary": ["keto_friendly", "vegetarian", "gluten_free"],
        "confidence": 0.98
      },
      {
        "name": "Sourdough Toast",
        "quantity": 1,
        "serving_size": 1,
        "serving_unit": "medium slice (40g)",
        "weight_g": 40,
        "calories": 95,
        "protein_g": 3.8,
        "carbs_g": 18.5,
        "fat_g": 0.6,
        "fiber_g": 1.2,
        "allergens": ["gluten"],
        "dietary": ["vegan", "vegetarian"],
        "confidence": 0.96
      },
      {
        "name": "Fresh Hass Avocado",
        "quantity": 0.5,
        "serving_size": 0.5,
        "serving_unit": "half avocado (50g)",
        "weight_g": 50,
        "calories": 80,
        "protein_g": 1.0,
        "carbs_g": 4.3,
        "fat_g": 7.3,
        "fiber_g": 3.4,
        "allergens": [],
        "dietary": ["vegan", "keto_friendly", "gluten_free"],
        "confidence": 0.95
      }
    ],
    "totals": {
      "calories": 319,
      "protein_g": 17.0,
      "carbs_g": 24.2,
      "fat_g": 17.7,
      "fiber_g": 4.6,
      "sugar_g": 1.2,
      "sodium_mg": 285
    },
    "macro_split": {
      "protein_pct": 21.3,
      "carbs_pct": 30.3,
      "fat_pct": 49.9
    },
    "assumptions": [
      "Eggs prepared with cooking spray rather than heavy butter",
      "Sourdough slice estimated at standard bakery thickness (40g)"
    ]
  },
  "meta": {
    "request_id": "req_9f81a204b7",
    "model": "foodvivo-neural-engine",
    "latency_ms": 28,
    "cached": true,
    "grounded": true
  }
}

POSTDual Barcode Intelligence

/v1/food/barcode

Hybrid barcode lookup combining FoodVivo Catalog Engine with proprietary serving size arbiter to normalize packaging portions (e.g. 2 scoops / 1 can instead of 100g default) with deterministic multiplier scaling.

Try this in Interactive Playground

Headers

Authorization:Bearer sk_live_your_api_key

Content-Type:application/json

Body Parameters

barcodestringrequired

8 to 14 digit UPC, EAN-13, or GTIN product barcode.

portion_multipliernumberoptional

Multiplier scaling factor (e.g. 0.5 for half portion, 2.0 for double serving).

Request (TYPESCRIPT)

const response = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/food/barcode", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    barcode: "3017620422003",
    portion_multiplier: 1.5,
  }),
});

const { data } = await response.json();
console.log(data.product_name, data.calculated_portion);

Response:

{
  "success": true,
  "data": {
    "barcode": "3017620422003",
    "product_name": "Nutella Hazelnut Spread with Cocoa",
    "brand": "Ferrero",
    "category": "Spreads & Condiments",
    "serving_size_label": "2 tbsp (37g)",
    "serving_weight_g": 37,
    "per_serving": {
      "calories": 200,
      "protein_g": 2.0,
      "carbs_g": 22.0,
      "fat_g": 12.0,
      "fiber_g": 1.0,
      "sugar_g": 21.0,
      "sodium_mg": 15
    },
    "calculated_portion": {
      "multiplier": 1.5,
      "calories": 300,
      "protein_g": 3.0,
      "carbs_g": 33.0,
      "fat_g": 18.0,
      "fiber_g": 1.5,
      "sugar_g": 31.5,
      "sodium_mg": 23
    },
    "allergens": ["tree_nuts", "dairy", "soy"],
    "dietary": ["vegetarian", "gluten_free", "kosher"],
    "confidence": 0.99,
    "source": "foodvivo-catalog-engine"
  },
  "meta": {
    "request_id": "req_bc782910fa",
    "model": "foodvivo-catalog-engine",
    "latency_ms": 14,
    "cached": true
  }
}

POSTMulti-Photo Panoramic Label OCR

/v1/food/label

Nutrition Facts label OCR with multi-photo panoramic stitching for curved, cylindrical, or reflective packaging (e.g. hot sauce bottles, soda cans, multi-angle supplement tubs).

Try this in Interactive Playground

Headers

Authorization:Bearer sk_live_your_api_key

Content-Type:application/json

Body Parameters

imagesarrayrequired

Array of 1 to 5 image objects ({ url?: string, base64?: string }) captured at different angles.

package_contextstringoptional

Optional product hint (e.g., 'Sriracha 482g bottle').

Request (TYPESCRIPT)

const response = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/food/label", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    images: [{ image_url: "https://images.example.com/sriracha_nutrition.jpg" }],
    package_context: "Sriracha Hot Chili Sauce 482g",
  }),
});

const { data } = await response.json();
console.log("Serving:", data.serving_size_label);
console.log("Per Serving:", data.per_serving);

Response:

{
  "success": true,
  "data": {
    "product_name": "Sriracha Hot Chili Sauce",
    "brand": "Huy Fong Foods",
    "servings_per_container": 96,
    "serving_size_label": "1 tsp (5g)",
    "serving_weight_g": 5,
    "per_serving": {
      "calories": 5,
      "protein_g": 0.0,
      "carbs_g": 1.0,
      "fat_g": 0.0,
      "fiber_g": 0.0,
      "sugar_g": 1.0,
      "added_sugar_g": 1.0,
      "sodium_mg": 80
    },
    "ingredients_text": "Chili, Sugar, Salt, Garlic, Acetic Acid, Potassium Sorbate, Sodium Bisulfite, Xanthan Gum.",
    "allergens": [],
    "dietary": ["vegan", "gluten_free", "kosher"],
    "stitched_photos_count": 2,
    "confidence": 0.98,
    "assumptions": ["Curved cylindrical label perspective unrolled with 98.4% OCR fidelity"]
  },
  "meta": {
    "request_id": "req_lbl_8120489",
    "model": "foodvivo-vision-engine",
    "latency_ms": 482,
    "stitched_photos": 2,
    "cached": false
  }
}

POSTDeterministic Portion Scaling

/v1/meal/portion/estimate

Recalculate nutrition and macro breakdown for adjusted portion or weight multipliers in 0ms without AI overhead or token costs.

Headers

Authorization:Bearer sk_live_your_api_key

Content-Type:application/json

Body Parameters

foodobjectrequired

Valid FoodItem object returned from /v1/food/analyze or /v1/food/barcode.

target_serving_sizenumberoptional

Desired serving count (e.g. 1.5, 2.0).

target_weight_gnumberoptional

Target scale weight in grams (e.g. 250).

Request (TYPESCRIPT)

const response = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/meal/portion/estimate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    food: rawFoodItem,
    target_weight_g: 225,
  }),
});

const { data, meta } = await response.json();
console.log("Scaled Calories:", data.calories, "Scale Factor:", meta.scale_factor);

Response:

{
  "success": true,
  "data": {
    "name": "Grilled Chicken Breast",
    "quantity": 1.5,
    "serving_size": 1.5,
    "serving_unit": "breast (150g)",
    "weight_g": 225,
    "calories": 372,
    "protein_g": 69.8,
    "carbs_g": 0.0,
    "fat_g": 8.0,
    "allergens": [],
    "dietary": ["gluten_free", "high_protein"],
    "confidence": 0.98
  },
  "meta": {
    "scale_factor": 1.5,
    "calculation": "deterministic_scaling"
  }
}

POSTDaily Multi-Course Aggregation

/v1/meal/daily/analyze

Batch analyze multi-course daily food intake (breakfast, lunch, dinner, snacks) and calculate goal compliance against target calorie and macronutrient budgets.

Headers

Authorization:Bearer sk_live_your_api_key

Content-Type:application/json

Body Parameters

mealsarrayrequired

Array of meal objects with 'meal_type' ('breakfast'|'lunch'|'dinner'|'snack') and 'input' ({ text, image_url, image_base64 }).

user_goalsobjectoptional

Optional target nutrition budget ({ target_calories, target_protein_g, target_carbs_g, target_fat_g }).

Request (TYPESCRIPT)

const response = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/meal/daily/analyze", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    meals: [
      { meal_type: "breakfast", input: { text: "2 eggs, avocado toast" } },
      { meal_type: "lunch", input: { text: "Grilled chicken salad" } },
    ],
    user_goals: { target_calories: 2000, target_protein_g: 140 },
  }),
});

const { data } = await response.json();
console.log("Daily Totals:", data.daily_totals);
console.log("Goal Progress:", data.goal_progress);

Response:

{
  "success": true,
  "data": {
    "daily_totals": {
      "calories": 1780,
      "protein_g": 142.5,
      "carbs_g": 128.0,
      "fat_g": 64.2,
      "fiber_g": 26.4,
      "sugar_g": 18.1,
      "sodium_mg": 1850
    },
    "goal_progress": {
      "calories": {
        "target": 2000,
        "consumed": 1780,
        "remaining": 220,
        "percentage_met": 89
      },
      "protein": {
        "target": 150,
        "consumed": 142.5,
        "remaining": 7.5,
        "percentage_met": 95
      }
    },
    "all_foods": [
      { "name": "Scrambled Eggs", "meal_type": "breakfast", "calories": 144 },
      { "name": "Grilled Chicken Caesar", "meal_type": "lunch", "calories": 520 },
      { "name": "Salmon with Quinoa", "meal_type": "dinner", "calories": 680 }
    ],
    "assumptions": ["Standard restaurant salad dressings applied in reasonable portion"]
  }
}

POSTContinuous Evaluation Feedback

/v1/feedback

Submit end-user accuracy ratings, thumbs up/down, or clinician scale corrections to continuous golden eval benchmarks with zero regression drift.

Headers

Content-Type:application/json

Authorization:Bearer sk_live_... (optional)

Body Parameters

request_idstringoptional

Trace request ID from /v1/food/analyze or /v1/food/barcode.

ratingnumberrequired

1 for positive/accurate, -1 for issue reported (or 1 to 5 integer rating).

feedback_typestringoptional

input_querystringoptional

Original meal text or context submitted by user.

user_correctionobjectoptional

Corrected ground-truth values (e.g. { actual_calories: 450, verified_grams: 180 }).

commentstringoptional

Developer or user notes explaining the adjustment.

Request (TYPESCRIPT)

const response = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/feedback", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    request_id: "req_8f12a9c403b1",
    rating: 1,
    feedback_type: "accurate",
    input_query: "1 large Hass avocado",
    user_correction: { calories: 240 },
  }),
});

const result = await response.json();
console.log(result.message);

Response:

{
  "success": true,
  "data": {
    "id": "fb_7a02b4d1",
    "request_id": "req_8f12a9c403b1",
    "feedback_type": "accurate",
    "rating": 1
  },
  "message": "Feedback recorded successfully. Thank you for contributing to FoodVivo ground-truth evaluations!"
}

GETCustomer Feedback Metrics

/v1/feedback/stats

Returns aggregate feedback statistics, satisfaction rate, and accuracy benchmark metrics for the authenticated customer account.

Headers

Authorization:Bearer sk_live_your_api_key

Request (TYPESCRIPT)

const res = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/feedback/stats", {
  headers: { "Authorization": "Bearer sk_live_your_api_key" }
});
const { data } = await res.json();
console.log("Positive Rate:", data.positiveRate, "%");

Response:

{
  "success": true,
  "data": {
    "total": 342,
    "positive": 339,
    "negative": 3,
    "positiveRate": 99.1
  }
}

POSTCreate Scoped Developer API Key

/v1/keys

Programmatically generate a new scoped live or test API key for an enterprise customer or development environment.

Headers

Content-Type:application/json

Body Parameters

namestringrequired

Descriptive label for the API key (e.g. 'Production iOS App').

customer_idstringrequired

Unique customer/organization identifier.

tierstringoptional

Plan tier: 'starter' | 'hobby' | 'developer' | 'growth' | 'scale'.

is_testbooleanoptional

Set to true to generate a test mode key (prefixed with sk_test_).

Request (TYPESCRIPT)

const response = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/keys", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Production Mobile App",
    customer_id: "cust_12345",
    tier: "developer",
  }),
});

const { data } = await response.json();
console.log("New API Key:", data.key);

Response:

{
  "success": true,
  "data": {
    "id": "key_e4f901ab",
    "name": "Production Mobile App",
    "customerId": "cust_12345",
    "tier": "developer",
    "key": "sk_live_9f83a0bc172849e0a293847561028374",
    "prefix": "sk_live_9f83",
    "monthlyQuota": 25000,
    "rpmLimit": 600,
    "isTest": false,
    "createdAt": "2026-08-27T00:00:00.000Z"
  },
  "message": "API key created successfully. Store this key securely; it will not be displayed again."
}

GETCluster Health & Telemetry

/v1/health

Public health check endpoint returning edge network status, neural inference engine availability, and cluster latency telemetry.

Headers

Request (TYPESCRIPT)

const res = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/health");
const data = await res.json();
console.log("Status:", data.status, "Environment:", data.environment);

Response:

{
  "status": "healthy",
  "service": "foodvivo-api",
  "version": "1.0.0",
  "environment": "production",
  "timestamp": "2026-08-27T00:00:00.000Z",
  "services": {
    "neural_engine": "operational",
    "vision_ocr": "operational",
    "edge_cache": "operational",
    "catalog_pipeline": "operational",
    "auth_core": "operational"
  }
}

GETPublic Payment Configuration

/v1/payments/config

Retrieve public Razorpay configuration, key IDs, supported currencies (INR, USD), and current tier pricing matrices.

Headers

Request (TYPESCRIPT)

const res = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/payments/config");
const { data } = await res.json();
console.log("Razorpay Key:", data.keyId, "Currencies:", data.supportedCurrencies);

Response:

{
  "success": true,
  "data": {
    "keyId": "rzp_live_key",
    "isConfigured": true,
    "supportedCurrencies": ["INR", "USD"],
    "plans": {
      "hobby": { "name": "Hobby", "priceINR": 2400, "priceUSD": 29, "monthlyQuota": 5000, "rpmLimit": 120 },
      "developer": { "name": "Developer", "priceINR": 6500, "priceUSD": 79, "monthlyQuota": 25000, "rpmLimit": 600 },
      "growth": { "name": "Growth", "priceINR": 16500, "priceUSD": 199, "monthlyQuota": 100000, "rpmLimit": 2400 }
    }
  }
}

POSTCreate Recurring Subscription

/v1/payments/create-subscription

Generate a recurring Razorpay subscription checkout session for Hobby, Developer, or Growth plans.

Headers

Content-Type:application/json

Body Parameters

tierstringrequired

Target plan tier: 'hobby' | 'developer' | 'growth'.

customer_idstringrequired

Unique account ID of the customer.

customer_emailstringoptional

Email address for transaction receipts.

currencystringoptional

'INR' or 'USD'.

Request (TYPESCRIPT)

const response = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/payments/create-subscription", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    tier: "developer",
    customer_id: "cust_12345",
    currency: "USD",
  }),
});
const { data } = await response.json();
console.log("Subscription ID:", data.subscriptionId);

Response:

{
  "success": true,
  "data": {
    "subscriptionId": "sub_Nf81938a12",
    "planId": "plan_developer_usd",
    "amount": 7900,
    "currency": "USD",
    "tier": "developer",
    "keyId": "rzp_live_key",
    "planName": "FoodVivo Developer Plan"
  }
}

POSTVerify Subscription Signature

/v1/payments/verify-subscription

Verify Razorpay subscription HMAC SHA-256 signature and instantly upgrade monthly request quotas and RPM limits.

Headers

Content-Type:application/json

Body Parameters

razorpay_subscription_idstringrequired

Subscription ID from Razorpay checkout.

razorpay_payment_idstringrequired

Payment transaction ID.

razorpay_signaturestringrequired

HMAC SHA-256 signature.

customer_idstringrequired

Customer account ID.

tierstringrequired

'hobby' | 'developer' | 'growth'.

Request (TYPESCRIPT)

const res = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/payments/verify-subscription", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    razorpay_subscription_id: subId,
    razorpay_payment_id: payId,
    razorpay_signature: signature,
    customer_id: customerId,
    tier: "developer",
  }),
});

Response:

{
  "success": true,
  "data": {
    "success": true,
    "tier": "developer",
    "monthlyQuota": 25000,
    "rpmLimit": 600,
    "subscriptionId": "sub_Nf81938a12",
    "message": "Subscription verified and plan upgraded to developer successfully."
  }
}

POSTCreate Upgrade Order

/v1/payments/create-order

Generate a new one-time Razorpay checkout order for plan upgrades (Hobby, Developer, Growth).

Headers

Content-Type:application/json

Body Parameters

tierstringrequired

'hobby' | 'developer' | 'growth'

customer_idstringrequired

Customer account ID

customer_emailstringoptional

Optional receipt email

currencystringoptional

'INR' | 'USD'

Request (TYPESCRIPT)

const res = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/payments/create-order", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ tier: "developer", customer_id: "cust_12345", currency: "USD" })
});

Response:

{
  "success": true,
  "data": {
    "orderId": "order_8f12a9c403b1",
    "amount": 7900,
    "currency": "USD",
    "tier": "developer",
    "keyId": "rzp_live_key",
    "receipt": "rcpt_developer_12345",
    "planName": "FoodVivo Developer Plan"
  }
}

POSTVerify Order Payment

/v1/payments/verify

Verify Razorpay one-time payment HMAC signature and instantly upgrade monthly quota and RPM limits.

Headers

Content-Type:application/json

Body Parameters

razorpay_order_idstringrequired

Razorpay Order ID

razorpay_payment_idstringrequired

Razorpay Payment ID

razorpay_signaturestringrequired

HMAC SHA-256 Signature

customer_idstringrequired

Customer account ID

tierstringrequired

'hobby' | 'developer' | 'growth'

Request (TYPESCRIPT)

const res = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/payments/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ razorpay_order_id: "order_123", razorpay_payment_id: "pay_123", razorpay_signature: "sig", customer_id: "cust_12345", tier: "developer" })
});

Response:

{
  "success": true,
  "data": {
    "success": true,
    "tier": "developer",
    "monthlyQuota": 25000,
    "rpmLimit": 600,
    "message": "Payment verified and account upgraded to developer tier."
  }
}

GETCustomer Billing History

/v1/payments/history/:customerId

Fetch billing history, payment invoices, and transaction receipts for a specific customer account.

Headers

Body Parameters

customerIdstringrequired

Customer account identifier in URL path.

Request (TYPESCRIPT)

const res = await fetch("https://foodvivo-api.flappybird-assets.workers.dev/v1/payments/history/cust_12345");
const { data } = await res.json();
console.log("Invoices:", data);

Response:

{
  "success": true,
  "data": [
    {
      "id": "txn_8120489",
      "customer_id": "cust_12345",
      "tier": "developer",
      "amount": 7900,
      "currency": "USD",
      "status": "paid",
      "created_at": "2026-08-26T12:00:00.000Z"
    }
  ]
}

Developer Quickstarts across 8 Popular Stacks

Complete end-to-end integration examples with package installations, client wrappers, and macro parsing for modern mobile and web applications.

1. HTTP Client / Dependencies

// Standard fetch (Node.js 18+, Bun, Deno, Next.js, React Native)

2. Complete Integration Client

const FOODVIVO_API_KEY = process.env.FOODVIVO_API_KEY || "sk_live_your_key";
const API_URL = "https://foodvivo-api.flappybird-assets.workers.dev";

async function main() {
  const res = await fetch(`${API_URL}/v1/food/analyze`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${FOODVIVO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "2 scrambled eggs, avocado toast, and 1 black coffee",
      context: "Breakfast",
    }),
  });

  const { data } = await res.json();
  console.log("Meal Breakdown:", data.meal_title);
  console.log("Calories:", data.totals.calories, "kcal");
  console.log("Protein:", data.totals.protein_g, "g");
}

main().catch(console.error);

HTTP Status Codes & Error Dictionary

FoodVivo returns standard HTTP status codes and structured JSON error objects containing an error code, message, and actionable recommendation.

Status	Code	Description & Recommendation
400	INVALID_REQUEST_BODY	The JSON payload was malformed, missing required fields, or failed boundary validation. Action: Inspect the 'details' array in the response to fix invalid parameter values.
401	UNAUTHORIZED	Missing or invalid API key in Authorization or X-API-Key headers. Action: Provide a valid 'Authorization: Bearer sk_live_...' header from your dashboard.
500	MISSING_API_KEY	Cloudflare Worker runtime binding is missing required environment variables. Action: Contact FoodVivo status center or verify production secrets.
404	BARCODE_NOT_FOUND	The submitted UPC/EAN barcode does not exist in our global catalog registry. Action: Fallback to POST /v1/food/label to scan the Nutrition Facts panel directly with OCR.
429	RATE_LIMIT_EXCEEDED	Your API key exceeded its tier's Requests Per Minute (RPM) threshold. Action: Implement exponential backoff or upgrade to Developer/Growth tier for higher RPM.
429	QUOTA_EXCEEDED	Your account has reached its monthly request allowance. Action: Upgrade your plan in the Billing Dashboard to instantly restore unlimited throughput.
429	PLAYGROUND_RATE_LIMIT	Anonymous public playground IP rate limit (5 requests/min) exceeded. Action: Sign in to generate a developer API key with 1,000 free monthly requests.
403	FORBIDDEN_ORIGIN	Playground endpoint called from an unauthorized external domain. Action: Use the official authenticated endpoints (/v1/food/*) with your developer API key.
404	NOT_FOUND	The requested route does not exist. Action: Check the URL path against /v1/docs or the documentation reference.
500	INTERNAL_SERVER_ERROR	Unexpected exception during neural inference or database lookup. Action: Retry the request with a fresh X-Request-Id header. Our on-call engineers are automatically alerted.