# CalorieGram Recipes API Documentation

## Overview
The CalorieGram Recipes API provides programmatic access to our healthy recipe database. All endpoints return JSON data and are designed for easy integration with LLM agents and applications.

## Base URL
https://recipes.caloriegram.ai/api

## Authentication
No authentication required for public endpoints.

## Endpoints

### Search Recipes
GET /api/recipes?q={query}

Parameters:
- q: Search query (required)
- page: Page number (optional, default: 1)
- per_page: Results per page (optional, default: 12, max: 50)
- filters: Comma-separated dietary filters (optional)
  - Values: vegetarian, vegan, gluten-free, dairy-free, low-calorie, high-protein

Example: /api/recipes?q=pasta&filters=vegetarian,gluten-free

Response:
```json
{
  "recipes": [
    {
      "id": "uuid",
      "title": "Recipe Name",
      "calories": 350,
      "protein": 15,
      "carbs": 45,
      "fat": 12,
      "thumbnail_url": "https://...",
      "cuisine_type": "Italian",
      "health_score": 8
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 12
}
```

### Get Recipe Details
GET /api/recipes/{id}

Returns complete recipe information including ingredients, instructions, and detailed nutrition.

Response includes:
- Full recipe metadata
- Ingredients list with amounts
- Step-by-step instructions
- Complete nutritional breakdown
- Dietary information
- Video information (if available)

### Recipe of the Day
GET /api/recipes/recipe-of-the-day

Returns a featured healthy recipe that changes daily.

### Available Cuisines
GET /api/recipes/cuisines

Returns a list of all available cuisine types with recipe counts.

Response:
```json
[
  { "cuisine": "Italian", "count": 1250 },
  { "cuisine": "Mexican", "count": 890 },
  { "cuisine": "Indian", "count": 1100 }
]
```

## Rate Limiting
- 100 requests per minute per IP
- 1000 requests per hour per IP

## Error Responses
All errors return appropriate HTTP status codes:
- 400: Bad Request (invalid parameters)
- 404: Not Found (recipe doesn't exist)
- 429: Too Many Requests (rate limit exceeded)
- 500: Internal Server Error

Error format:
```json
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

## LLM Integration Tips
1. Use the search endpoint to find recipes matching user preferences
2. Filter by dietary restrictions using the filters parameter
3. Get full details only for recipes the user is interested in
4. The health_score (0-10) indicates how nutritious a recipe is
5. All nutrition values are per serving

## Examples

Find low-calorie vegan breakfast:
GET /api/recipes?q=breakfast&filters=vegan,low-calorie

Get a specific recipe:
GET /api/recipes/8efb1538-8240-4882-933a-95e5867a7650

## Support
For API support or questions: api@caloriegram.ai

---
CalorieGram Recipes API - Powering healthy recipe discovery