Skip to main content

​
Overview

The Events API allows you to log, update, and query baby activities. All events are associated with a baby profile and can include optional caregiver attribution, photos, and notes.

​
Event Types

Zen Nurture supports the following event types:

Feeding

  • FEED_BOTTLE: Bottle feeding (formula, breast milk, cow milk)
  • FEED_BREAST: Breastfeeding sessions

Diaper

  • DIAPER: Diaper changes (wet, dirty, mixed)

Sleep

  • SLEEP: Sleep sessions with start and end times

Medicine

  • MED_DOSE: Medicine doses with name and amount

Growth

  • GROWTH_WEIGHT: Weight measurements
  • GROWTH_LENGTH: Length/height measurements
  • GROWTH_HEAD_CIRC: Head circumference

Notes

  • NOTE: General notes and observations

​
Event Schema

interface Event {
  _id: Id<"events">;
  babyId: Id<"babyProfiles">;
  type: string;
  timestamp: string; // ISO 8601
  caregiverId?: Id<"caregivers">;
  payload?: any;
  source?: string;
  loggedBy?: string; // user ID who logged it
  loggedByName?: string;
  photoIds?: string[];
  createdAt: string;
  updatedAt?: string;
}

​
Create Event

import { useMutation } from "convex/react";
import { api } from "./convex/_generated/api";

const createEvent = useMutation(api.events.createEvent);

await createEvent({
  babyId,
  type: "FEED_BOTTLE",
  timestamp: new Date().toISOString(),
  caregiverId,
  payload: {
    amountMl: 120,
    contentType: "formula",
    formulaName: "Similac Pro-Advance",
    notes: "Fed well"
  }
});

​
Parameters

​
babyId
Id<'babyProfiles'>
required
The baby profile ID this event belongs to
​
type
string
required
Event type (FEED_BOTTLE, DIAPER, SLEEP, etc.)
​
timestamp
string
required
ISO 8601 timestamp when the event occurred
​
caregiverId
Id<'caregivers'>
Optional caregiver who performed the activity
​
payload
object
Event-specific data (structure varies by event type)
​
photoIds
string[]
Array of photo IDs attached to this event

​
Response

​
_id
Id<'events'>
The newly created event ID

​
Update Event

Update an existing event’s data. 
const updateEvent = useMutation(api.events.updateEvent);

await updateEvent({
  id: eventId,
  timestamp: new Date().toISOString(),
  payload: {
    amountMl: 150, // Updated amount
    contentType: "formula"
  }
});

​
Parameters

​
id
Id<'events'>
required
The event ID to update
​
timestamp
string
Updated timestamp
​
payload
object
Updated payload data (merges with existing)
​
photoIds
string[]
Updated photo IDs

​
Delete Event

Delete an event permanently. 
const deleteEvent = useMutation(api.events.deleteEvent);

await deleteEvent({ id: eventId });

​
Parameters

​
id
Id<'events'>
required
The event ID to delete

​
Get Daily Aggregates

Retrieve summarized statistics for a specific date. 
const dailyAggregates = useQuery(api.events.getDailyAggregates, {
  babyId,
  date: "2024-03-05" // YYYY-MM-DD format
});

​
Parameters

​
babyId
Id<'babyProfiles'>
required
The baby profile ID
​
date
string
required
Date in YYYY-MM-DD format

​
Response

{
  feeds: {
    count: 8,
    totalMl: 960,
    avgMl: 120,
    bottleCount: 6,
    breastCount: 2
  },
  diapers: {
    total: 6,
    wet: 4,
    dirty: 1,
    mixed: 1
  },
  sleeps: {
    count: 4,
    totalMinutes: 780,
    avgMinutes: 195,
    longestMinutes: 420
  },
  meds: {
    count: 2,
    doses: [
      { medicineName: "Tylenol", count: 2 }
    ]
  }
}

​
Get Range Aggregates

Retrieve aggregates for a date range. 
const rangeAggregates = useQuery(api.events.getRangeAggregates, {
  babyId,
  from: "2024-03-01T00:00:00Z",
  to: "2024-03-07T23:59:59Z"
});

​
Parameters

​
babyId
Id<'babyProfiles'>
required
The baby profile ID
​
from
string
required
Start timestamp (ISO 8601)
​
to
string
required
End timestamp (ISO 8601)

​
Response

Same structure as daily aggregates, but covering the entire range.

​
Get Last Events by Types

Retrieve the most recent event for each specified type. 
const lastEvents = useQuery(api.events.getLastEventsByTypes, {
  babyId,
  eventTypes: ["FEED_BOTTLE", "FEED_BREAST", "DIAPER", "SLEEP"]
});

​
Parameters

​
babyId
Id<'babyProfiles'>
required
The baby profile ID
​
eventTypes
string[]
required
Array of event types to query

​
Response

{
  FEED_BOTTLE: { /* last bottle feed event */ },
  FEED_BREAST: { /* last breastfeed event */ },
  DIAPER: { /* last diaper change */ },
  SLEEP: { /* last sleep event */ }
}

​
Best Practices

Use new Date().toISOString() to ensure consistent timestamp formatting. The API validates timestamps and rejects invalid formats.
Each event type has specific payload requirements. Validate required fields before submission to avoid errors.
All timestamps are stored in UTC. The baby profile’s timezone setting is used for display purposes only.
Always include caregiverId when logging events to properly attribute activities to the correct caregiver.

Baby Profiles

Manage baby profiles and settings

Families

Family and caregiver management

Reminders

Set up event-based reminders

Activity Tracking

Learn about activity tracking features

Build docs developers (and LLMs) love

Get started for freeTalk to us