Household Management API: Build Smart Home Integrations with Victualia

What is a Household Management API?

A household management API gives developers programmatic access to home organization data—inventory tracking, meal plans, shopping lists, recipes, tasks, and more. Instead of building these systems from scratch, you can integrate with a proven platform and focus on your unique use case.

Victualia offers a production-ready household management API with 74+ REST endpoints covering everything from pantry inventory to travel itineraries. Whether you're building a smart fridge integration, a voice assistant skill, or a custom dashboard, our API provides the foundation.

Get your API key to start building today.

API Overview

Authentication

All requests require an API key passed as a Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.victualia.app/api/v1/homes

API keys are available to Premium subscribers. Generate yours in Settings → API Keys.

Core Resources

The API is organized around homes—all other resources are scoped to a specific home, enabling multi-property support.

Homes

Homes are the top-level container. A user can have multiple homes (vacation property, shared household, etc.).

# List all homes
GET /homes

# Create a new home
POST /homes
{
  "name": "Beach House",
  "measurementSystem": "metric"
}

# Get a specific home
GET /homes/{homeId}

Items (Inventory)

Track everything in your household—pantry staples, fridge contents, freezer items, cleaning supplies, and more.

# List all items in a home
GET /homes/{homeId}/items

# Add a new item
POST /homes/{homeId}/items
{
  "name": "Olive Oil",
  "location": "pantry",
  "quantity": 1,
  "unit": "bottle",
  "expirationDate": "2026-06-15"
}

# Update quantity (e.g., after using some)
PATCH /homes/{homeId}/items/{id}/quantity
{
  "quantity": 0.5
}

Key features:

• Track items by location (pantry, fridge, freezer, garage, etc.)
• Expiration date tracking with alerts
• Purchase history
• Barcode scan support in the iOS/Android apps
• Low-stock thresholds for automatic shopping list generation

Recipes

Store and organize recipes with full ingredient lists, nutritional info, and cooking instructions.

# List recipes
GET /homes/{homeId}/recipes

# Get recipe gallery (with images)
GET /homes/{homeId}/recipes/gallery

# Create a recipe
POST /homes/{homeId}/recipes
{
  "name": "Pasta Carbonara",
  "servings": 4,
  "prepTime": 10,
  "cookTime": 20,
  "difficulty": "medium",
  "ingredients": [...],
  "steps": [...]
}

# Generate shopping list from recipe
POST /homes/{homeId}/recipes/{id}/shopping-lists

Recipe metadata options:

• 13 cuisine types (Italian, Mexican, Japanese, etc.)
• Meal types (breakfast, lunch, dinner, snack)
• 15 dietary tags (vegetarian, vegan, gluten-free, dairy-free, etc.)
• Difficulty levels (easy, medium, hard)
• AI generation tracking (provider, model, prompt used)

Meal Plans

Weekly or monthly meal planning with AI generation support.

# List meal plans
GET /homes/{homeId}/meal-plans

# Create a meal plan
POST /homes/{homeId}/meal-plans
{
  "name": "Week of Jan 20",
  "startDate": "2026-01-20",
  "endDate": "2026-01-26"
}

# Add a meal to a slot
POST /homes/{homeId}/meal-plans/{id}/slots
{
  "date": "2026-01-20",
  "mealType": "dinner",
  "recipeId": "recipe_abc123"
}

# Accept AI-generated meal plan
POST /homes/{homeId}/meal-plans/{id}/accept

Shopping Lists

Create and manage shopping lists with collected/remaining tracking.

# List shopping lists
GET /homes/{homeId}/shopping-lists

# Create a shopping list
POST /homes/{homeId}/shopping-lists
{
  "name": "Weekly Groceries"
}

# Add item to list
POST /homes/{homeId}/shopping-lists/{id}/items
{
  "name": "Milk",
  "quantity": 2,
  "unit": "liters"
}

# Mark item as collected
PATCH /homes/{homeId}/shopping-lists/{id}/items/{itemId}/quantity
{
  "collectedQuantity": 2
}

Smart list features:

• Auto-generated "Running Low" list from inventory thresholds
• Auto-generated "Weekly Meals" list from meal plan ingredients
• Collected vs. desired quantity tracking
• Cross off items while shopping

Assets

Track home appliances, furniture, electronics—with warranty and document management.

# List assets
GET /homes/{homeId}/assets

# Create an asset
POST /homes/{homeId}/assets
{
  "name": "Dishwasher",
  "brand": "Bosch",
  "model": "SMS46GI01E",
  "purchaseDate": "2024-03-15",
  "warrantyExpiration": "2027-03-15",
  "location": "kitchen"
}

# Attach a document (warranty, manual, receipt)
POST /homes/{homeId}/assets/{id}/documents
{
  "name": "Warranty Certificate",
  "type": "warranty",
  "url": "https://..."
}

Task Lists & Tasks

Household to-do management with ordering and completion tracking.

# List task lists
GET /homes/{homeId}/task-lists

# Create a task
POST /homes/{homeId}/task-lists/{listId}/tasks
{
  "title": "Clean gutters",
  "dueDate": "2026-02-01"
}

# Reorder tasks
POST /homes/{homeId}/task-lists/{listId}/tasks/{taskId}/reorder
{
  "position": 1
}

Trips

Travel itinerary management with support for flights, hotels, activities, and more.

# List trips
GET /homes/{homeId}/trips

# Create a trip
POST /homes/{homeId}/trips
{
  "name": "Paris Vacation",
  "startDate": "2026-05-01",
  "endDate": "2026-05-08",
  "destination": "Paris, France"
}

# Add a flight
POST /homes/{homeId}/trips/{tripId}/items
{
  "type": "flight",
  "title": "Outbound Flight",
  "startTime": "2026-05-01T08:00:00Z",
  "confirmationNumber": "ABC123"
}

Events (Calendar)

Household calendar with completion and cancellation workflows.

# List events
GET /homes/{homeId}/events?start=2026-01-01&end=2026-01-31

# Create an event
POST /homes/{homeId}/events
{
  "title": "Dentist Appointment",
  "startTime": "2026-01-25T14:00:00Z",
  "endTime": "2026-01-25T15:00:00Z"
}

# Mark event as complete
POST /homes/{homeId}/events/{id}/complete

Error Handling

All errors return a consistent JSON structure:

{
  "error": {
    "code": "not-found",
    "message": "Item not found"
  }
}

Error codes:

Common Integration Patterns

Smart Fridge Integration

Query inventory and update quantities as items are used:

// Check what's in the fridge
const items = await fetch('/homes/{homeId}/items?location=fridge')
  .then(r => r.json());

// Update quantity when item is removed
await fetch('/homes/{homeId}/items/{id}/quantity', {
  method: 'PATCH',
  body: JSON.stringify({ quantity: newQuantity })
});

Voice Assistant Skill

"What's expiring this week?"

const items = await fetch('/homes/{homeId}/items')
  .then(r => r.json());

const expiringThisWeek = items.filter(item => {
  const expiry = new Date(item.expirationDate);
  const weekFromNow = new Date();
  weekFromNow.setDate(weekFromNow.getDate() + 7);
  return expiry <= weekFromNow;
});

Automated Shopping List

Generate a shopping list from the current meal plan:

// Get active meal plan
const mealPlans = await fetch('/homes/{homeId}/meal-plans').then(r => r.json());
const activePlan = mealPlans[0];

// Get entries with recipe details
const entries = await fetch(`/homes/{homeId}/meal-plans/${activePlan.id}/entries`)
  .then(r => r.json());

// Create shopping list from recipes
for (const entry of entries) {
  if (entry.recipeId) {
    await fetch(`/homes/{homeId}/recipes/${entry.recipeId}/shopping-lists`, {
      method: 'POST'
    });
  }
}

OpenAPI Specification

The full API specification is available at:

https://www.victualia.app/api/v1/openapi.json

Use it to:

• Generate client SDKs in any language
• Import into Postman or Insomnia
• Build documentation
• Validate requests/responses

MCP Server for AI Assistants

If you're building with AI assistants like Claude, consider using our MCP server instead of direct API calls. It provides a standardized interface that AI models understand natively.

{
  "mcpServers": {
    "victualia": {
      "command": "npx",
      "args": ["-y", "victualia-mcp"],
      "env": {
        "VICTUALIA_API_KEY": "your-api-key"
      }
    }
  }
}

Getting Started

1. Create a Victualia account at victualia.app
2. Subscribe to Premium to enable API access
3. Generate your API key in Settings → API Keys
4. Explore the API using the OpenAPI spec or examples above
5. Build something amazing and let us know what you create!

Frequently Asked Questions

What subscription is required for API access?

API access requires a Premium subscription. This includes both REST API access and the MCP server.

Is there a rate limit?

Yes, standard rate limits apply to prevent abuse. For high-volume integrations, contact us to discuss your use case.

Can I use this for commercial applications?

Yes, you can build commercial applications on top of the Victualia API. Each end user will need their own Victualia Premium subscription.

Is there a sandbox environment?

Currently, we don't offer a separate sandbox. We recommend creating a test home within your account for development.

How do I report bugs or request features?

Open an issue on our GitHub repository or contact support through the app.

---

Related Articles

• MCP Server for Home Management - AI assistant integration via Model Context Protocol
• Pantry Inventory App - Track your household inventory
• Family Organizer App - Manage your household together

---

Ready to build? Get your API key and start integrating household management into your application today.