REST API Guide

Direct API access with cURL examples and API key authentication

🔑 Authentication

⚠️

Important: How to Get Your API Key

Sign up at nutrition.avocavo.app (email + password works fine)
Go to Dashboard → API Keys section
Generate API key → Copy it (starts with sk_live_ or sk_test_)
Use in X-API-Key header for all requests

API Key Authentication

All requests require an API key in the X-API-Key header:

curl -X POST https://app.avocavo.app/api/v2/nutrition/ingredient \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_YOUR_API_KEY_HERE" \
  -d '{"ingredient": "1 cup brown rice"}'

💡

Using NPM/Python Packages with Email/Password Accounts

If you signed up with email/password (not OAuth):

NPM CLI Package:

# Set API key as environment variable

export AVOCAVO_API_KEY="sk_test_YOUR_KEY"

# Or pass directly in command

avocavo --api-key "sk_test_YOUR_KEY" ingredient "1 cup rice"

Python Package:

import avocavo as av

# Instead of av.login(), use:

av.set_api_key("sk_test_YOUR_KEY")

# Then use normally

result = av.analyze_ingredient("1 cup rice")

Node.js/JavaScript:

const { NutritionAPI } = require('avocavo');

// Initialize with API key

const api = new NutritionAPI('sk_test_YOUR_KEY');

const result = await api.analyzeIngredient('1 cup rice');

⚠️ avocavo login and av.login() only work with OAuth (Google/GitHub) accounts

🌐 Base URL

https://app.avocavo.app/api/v2/nutrition/

All endpoints use v2 (not v1). All requests are POST with JSON body.

🎯 Endpoints

1. Single Ingredient

POST /api/v2/nutrition/ingredient

cURL Example:

curl -X POST https://app.avocavo.app/api/v2/nutrition/ingredient \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -d '{
    "ingredient": "1 cup brown rice"
  }'

Response:

{
  "success": true,
  "ingredient": "1 cup brown rice",
  "nutrition": {
    "calories": 218.4,
    "protein": 4.52,
    "total_fat": 1.62,
    "saturated_fat": 0.33,
    "carbohydrates": 45.84,
    "fiber": 3.51,
    "sugar": 0.0,
    "calcium": 19.5,
    "iron": 1.03,
    "sodium": 1.95,
    "vitamin_a": null,
    "vitamin_c": null
    // ... 23 more nutrients
  },
  "metadata": {
    "usda_match": {
      "fdc_id": 168875,
      "description": "Rice, brown, medium-grain, cooked"
    },
    "usda_link": "https://fdc.nal.usda.gov/fdc-app.html#/food-details/168875/nutrients",
    "match_quality": "good",
    "confidence": 0.611,
    "processing_time_ms": 2.5
  },
  "parsing": {
    "estimated_grams": 195.0,
    "ingredient_name": "cooked brown rice"
  }
}

2. Batch Ingredients

POST /api/v2/nutrition/batch

cURL Example:

curl -X POST https://app.avocavo.app/api/v2/nutrition/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -d '{
    "ingredients": [
      {"ingredient": "1 cup quinoa"},
      {"ingredient": "4 oz grilled salmon"}
    ]
  }'

Response:

{
  "success": true,
  "batch_size": 2,
  "results": [
    {
      "success": true,
      "ingredient": "1 cup quinoa",
      "nutrition": { "calories": 222.0, "protein": 8.14, ... },
      "metadata": {
        "usda_match": { "fdc_id": 168917, "description": "Quinoa, cooked" },
        "usda_link": "https://fdc.nal.usda.gov/fdc-app.html#/food-details/168917"
      }
    },
    {
      "success": true,
      "ingredient": "4 oz grilled salmon",
      "nutrition": { "calories": 391.23, "protein": 68.74, ... },
      "metadata": {
        "usda_match": { "fdc_id": 169813, "description": "Salmon, red (sockeye), filets with skin, smoked" },
        "usda_link": "https://fdc.nal.usda.gov/fdc-app.html#/food-details/169813"
      }
    }
  ],
  "summary": {
    "successful": 2,
    "failed": 0,
    "success_rate": 100.0,
    "total_processing_time_ms": 7856.43
  }
}

3. Recipe with Servings

POST /api/v2/nutrition/recipe

cURL Example:

curl -X POST https://app.avocavo.app/api/v2/nutrition/recipe \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -d '{
    "ingredients": [
      "2 cups all-purpose flour",
      "1 cup milk"
    ],
    "servings": 8
  }'

Response:

{
  "success": true,
  "recipe": {
    "servings": 8.0,
    "total_ingredients": 2
  },
  "nutrition": {
    "total": {
      "calories": 1058.84,
      "protein": 33.51,
      "carbohydrates": 202.49,
      // ... all nutrients for entire recipe
    },
    "per_serving": {
      "calories": 132.35,
      "protein": 4.19,
      "carbohydrates": 25.31,
      // ... per-serving breakdown
    },
    "ingredients": [
      {
        "ingredient": "2 cups all-purpose flour",
        "nutrition": { "calories": 910.0, "protein": 25.82, ... },
        "metadata": {
          "usda_match": { "fdc_id": 168936, "description": "Wheat flour, white, all-purpose, enriched, unbleached" }
        }
      },
      // ... other ingredients
    ]
  }
}

4. UPC/Barcode Search ✨ (NEW)

POST /api/v2/upc/ingredient

Search 4.4M+ products by UPC/barcode from USDA Branded Foods and Open Food Facts databases.

cURL Example:

curl -X POST https://app.avocavo.app/api/v2/upc/ingredient \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -d '{"upc": "041196912395"}'

Response:

{
  "success": true,
  "upc": "049000006346",
  "product": {
    "name": "Coca cola can cokes LG",
    "brand": "The Coca-Cola Company-0049000000016",
    "data_sources": ["usda_branded", "open_food_facts"],
    "fdc_id": 354198,
    "ingredients": "INGREDIENTS: CARBONATED WATER, HIGH FRUCTOSE CORN SYRUP...",
    "categories": []
  },
  "nutrition": {
    "coverage": "comprehensive",
    "source": "open_food_facts",
    "data": {
      "calories": 39.4,
      "protein": 0,
      "fat": 0,
      "carbohydrates": 11.0,
      "sodium": 12700,
      "serving_size": "100g serving",
      "serving_size_grams": 100,
      "per_100g": {
        "calories": 39.4,
        "protein": 0.0,
        "fat": 0.0,
        "carbohydrates": 11.0,
        "sodium": 12.7
      }
    },
    "note": "Raw nutrition values as stored in database - serving sizes vary by product"
  },
  "response_time_ms": 77
}

5. UPC/Barcode Batch Search ✨ (NEW)

POST /api/v2/upc/batch

Search multiple UPCs/barcodes in a single request for efficient batch processing.

cURL Example:

curl -X POST https://app.avocavo.app/api/v2/upc/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -d '{
    "upcs": ["041196912395", "123456789012", "999999999999"]
  }'

Response:

{
  "success": true,
  "summary": {
    "total": 3,
    "found": 2,
    "errors": 0
  },
  "results": [
    {
      "success": true,
      "upc": "041196912395",
      "product": {
        "product_name": "Peanut Butter Crunch",
        "brand": "LEWIS BAKE SHOP",
        "sources": ["usda_branded", "open_food_facts"]
      }
    },
    {
      "success": true,
      "upc": "123456789012",
      "product": {
        "product_name": "Test Product",
        "brand": "Test Brand",
        "sources": ["open_food_facts"]
      }
    },
    {
      "success": false,
      "upc": "999999999999",
      "error": "Product not found"
    }
  ],
  "processing_time_ms": 1146
}

⚠️ Important Notes

null Values

null = no USDA data available (not zero)

When a nutrient shows null, it means the USDA database doesn't have that information for this food, not that the food contains zero of that nutrient.

USDA Verification

Every response includes:

FDC ID: Official USDA FoodData Central ID
USDA Link: Direct link to verify the data
Description: Exact USDA food description

📊 Rate Limits & Batch Sizes

Plan	Monthly Calls	Batch Size	Rate Limit
Free	500 calls	3 ingredients	60/minute
Starter ($9/mo)	5K calls	10 ingredients	300/minute
Pro ($29/mo)	25K calls	25 ingredients	600/minute

🚨 Error Handling

Common HTTP Status Codes:

200 OK - Success
400 Bad Request - Invalid request format
401 Unauthorized - Missing/invalid API key
429 Too Many Requests - Rate limit exceeded
500 Server Error - Internal server error

Error Response Format:

{
  "success": false,
  "error": "invalid_api_key",
  "message": "The provided API key is not valid"
}