Skip to content

API Overview

Welcome to the MenoTime API documentation. MenoTime is a HIPAA-compliant health tech platform designed to collect and analyze de-identified clinical data on menopause from healthcare providers.

Architecture

The MenoTime API is built on modern, scalable technologies:

  • Framework: Python FastAPI
  • ORM: SQLAlchemy
  • Database: PostgreSQL
  • API Style: RESTful with JSON request/response bodies
  • Authentication: JWT (JSON Web Tokens)
  • Documentation: OpenAPI 3.0 / Swagger UI

Base URLs

Access the API using the appropriate base URL for your environment:

Environment Base URL
Development https://api-dev.menotime.timelessbiotech.com/v1
Staging https://api-staging.menotime.timelessbiotech.com/v1
Production https://api.menotime.timelessbiotech.com/v1

Interactive API Documentation

FastAPI automatically generates interactive API documentation. Access the Swagger UI to explore endpoints, test requests, and view response schemas:

  • Swagger UI: {baseURL}/docs
  • ReDoc: {baseURL}/redoc
  • OpenAPI Schema: {baseURL}/openapi.json

Example: https://api.menotime.timelessbiotech.com/v1/docs

API Versioning

The MenoTime API uses URL-based versioning (e.g., /v1) to maintain backward compatibility.

  • Current Version: v1
  • Deprecation Policy: Deprecated endpoints will be marked in responses and documented 12 months in advance
  • Legacy Support: v1 endpoints will remain supported for at least 2 years after v2 release

Rate Limiting

The API implements rate limiting to ensure fair usage and system stability.

Tier Requests Per Hour Burst Limit
Standard 1,000 100 requests/min
Premium 5,000 500 requests/min
Enterprise Unlimited Custom

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

When rate limit is exceeded, the API responds with HTTP 429 Too Many Requests.

Common Headers

Request Headers

Content-Type: application/json
Authorization: Bearer {jwt_token}
X-API-Key: {optional_api_key}
X-Request-ID: {optional_unique_identifier}

Response Headers

Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-Request-ID: {unique_identifier}

Data Format

All request and response bodies use JSON (JavaScript Object Notation):

{
  "status": "success",
  "data": {
    "id": "pat_123456",
    "name": "Patient Name"
  }
}

HTTPS and Security

  • All API endpoints require HTTPS (TLS 1.2+)
  • HTTP requests are automatically redirected to HTTPS
  • Unencrypted connections will be rejected

Pagination

List endpoints support pagination via query parameters:

GET /patients?page=1&limit=20

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Timestamps

All timestamps are returned in ISO 8601 format with UTC timezone:

2024-02-15T14:30:00Z

Getting Started

  1. Create an account and obtain API credentials
  2. Review the Authentication guide to understand JWT token flow
  3. Explore endpoints using the interactive Swagger UI at /docs
  4. Implement error handling as described in the Error Handling guide
  5. Test in development before deploying to production

Support

For API support and questions:

  • Email: api-support@timelessbiotech.com
  • Slack: #menotime-api-support
  • GitHub Issues: github.com/timelessbiotech/menotime-api