Skip to main content

API Reference

Welcome to the Eli Health API Reference documentation. This section provides comprehensive documentation of the metadata structures used throughout the Eli Health platform.

Metadata Architecture​

The Eli Health platform uses a hybrid storage approach for health measurement data:

Structured Data (Database Columns)​

  • id: Unique identifier
  • type: Record type classification
  • userId: User association
  • created/updated: Audit timestamps

Flexible Metadata (JSON)​

All measurement-specific data is stored in a flexible JSON metadata field:

  • Hormone measurements and classifications
  • Health scores and interpretations
  • Personalized recommendations
  • Time-based data (start/end dates, wake times)
  • Associated tags and context

Known Issues​

Dual Storage Pattern

The system currently has a confusing pattern where some fields exist in both database columns AND JSON metadata:

  • startDate / endDate
  • value

This requires fallback logic throughout the codebase:

const startDate = record?.metadata?.startDate || record?.startDate;

We are working to standardize this to a single source of truth.

Available APIs​

View Interactive API Documentation →​

Complete OpenAPI 3.0 specification documenting:

  • Record metadata structures for all measurement types
  • Reading history endpoints with metadata
  • Hormone-specific metadata fields
  • Heart rate and other measurement types

Data Access Patterns​

Direct API Access​

For authenticated users with appropriate permissions:

  • Query records with full metadata
  • Filter by date ranges and measurement types
  • Access personalized health interpretations

BigQuery Access​

For analytics and reporting:

  • Real-time replicated data from PostgreSQL
  • Full record table with metadata JSON
  • Requires specific IAM permissions

For most analytics users:

  • Curated, aggregated views
  • Built-in privacy controls
  • No direct database access required

Security Considerations​

All metadata fields contain sensitive health information:

  • Hormone values and classifications
  • Personal health interpretations
  • Medical recommendations

Access to these APIs requires:

  • Proper authentication (Firebase Auth + JWT)
  • Role-based permissions
  • Audit logging for compliance

Integration Guidelines​

When integrating with Eli Health APIs:

  1. Use metadata as primary source - Don't rely on column data that may be deprecated
  2. Handle both patterns - Until standardization is complete, check both locations for data
  3. Validate data types - Metadata structure varies by record type
  4. Respect rate limits - APIs are rate-limited for system stability

Support​

For API support or questions: