Skip to main content

​
Introduction

The Home Manager API is a RESTful API that allows you to manage household tasks, bills, shopping lists, maintenance items, and more. All endpoints require authentication through Clerk.

​
Base URL

All API requests should be made to: 
https://your-domain.com/api
For local development: 
http://localhost:3000/api

​
Authentication

All API endpoints require authentication using Clerk. The API uses Clerk’s server-side authentication to validate requests.

​
How Authentication Works

  • The API uses @clerk/nextjs/server for authentication
  • Each request is validated using auth() or getAuth(req) from Clerk
  • The authenticated user’s userId and email are extracted from the session
  • Users are automatically associated with a household upon authentication

​
Required Headers

When making requests from your frontend application, ensure Clerk’s session token is included in the request headers. Clerk’s client libraries handle this automatically. 
// Example using fetch with Clerk
import { useAuth } from '@clerk/nextjs';

const { getToken } = useAuth();
const token = await getToken();

fetch('/api/chores', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

​
Household Context

All resource endpoints (chores, bills, shopping, maintenance) automatically scope data to the authenticated user’s household:
  • When you make a request, the API calls getOrCreateHousehold(userId, email)
  • If the user doesn’t have a household, one is created automatically
  • All data operations are filtered by householdId to ensure data isolation

​
Common Response Formats

​
Success Response

Most successful requests return JSON data: 
{
  "id": "clx123...",
  "name": "Item name",
  "createdAt": "2024-03-15T10:30:00Z",
  // ... other fields
}

​
Error Responses

​
401 Unauthorized
string
Returned when authentication fails or user session is invalid.
Unauthorized
​
400 Bad Request
string
Returned when required fields are missing or invalid.
Missing fields
​
500 Internal Server Error
string
Returned when an unexpected server error occurs.
Internal Server Error

​
Error Handling

All endpoints follow a consistent error handling pattern:
  • 401 Unauthorized: User is not authenticated or session is invalid
  • 400 Bad Request: Missing required fields or invalid data
  • 404 Not Found: Resource not found or doesn’t belong to user’s household
  • 500 Internal Server Error: Unexpected server error

​
Example Error Handling

try {
  const response = await fetch('/api/chores', {
    method: 'POST',
    body: JSON.stringify({ name: 'Task', assignee: 'John' }),
  });

  if (!response.ok) {
    if (response.status === 401) {
      // Handle authentication error
    } else if (response.status === 400) {
      // Handle validation error
    }
  }

  const data = await response.json();
} catch (error) {
  // Handle network errors
}

​
Rate Limiting

Currently, there are no rate limits enforced on the API. However, it’s recommended to implement client-side throttling for frequent operations.

​
Data Types

​
Common Fields

Most resources include these common fields:

​
Pagination

Most list endpoints do not implement pagination and return all items for the household. The audit log endpoint supports optional pagination.

​
Reordering Items

Many endpoints (chores, bills, shopping, maintenance) support reordering items by position: 
// POST to the main endpoint with orderedIds
fetch('/api/chores', {
  method: 'POST',
  body: JSON.stringify({
    orderedIds: ['id1', 'id2', 'id3'] // New order
  }),
});
This updates the position field for each item based on array index.

​
Notifications

When certain actions occur (deleting items, completing tasks), the API automatically creates notifications:
  • Completing a chore creates a “Chore Completed” notification
  • Paying a bill creates a “Bill Paid” notification
  • Completing a shopping item creates an “Item Removed” notification
  • Finishing maintenance creates a “Maintenance Completed” notification
See the Notifications API for details.

​
Next Steps

Explore the specific API endpoints:

Build docs developers (and LLMs) love

Get started for freeTalk to us