Terra Menstruation API

openapi: 3.0.3
info:
  title: Terra Activity Menstruation API
  description: 'Terra is a unified wearables and health-data API that aggregates data from 500+ wearables, fitness trackers, and health apps (Garmin, Fitbit, Oura, Apple Health, Whoop, Strava, Google Fit, Polar, Withings, and more) behind a single normalized REST interface. Developers onboard end users through the Terra Widget or a custom authentication flow and then receive normalized Activity, Body, Daily, Sleep, Nutrition, Menstruation, and Athlete data.

    Terra''s primary delivery model is asynchronous. The data-read endpoints in this document accept a `to_webhook` flag (default true) that causes the requested payload to be fetched asynchronously and streamed to your configured webhook destination rather than returned inline. Newly available data is also pushed to that webhook as it arrives upstream. There is no WebSocket transport; server-to-developer delivery is HTTP webhook.

    All requests require two headers: `dev-id` (your public developer identifier) and `x-api-key` (your secret API key), both found in the Terra dashboard.'
  version: '2.0'
  contact:
    name: Terra
    url: https://tryterra.co
  license:
    name: Proprietary
    url: https://tryterra.co
servers:
- url: https://api.tryterra.co/v2
  description: Terra API v2
security:
- devId: []
  apiKey: []
tags:
- name: Menstruation
  description: Menstrual cycle and reproductive health data.
paths:
  /menstruation:
    get:
      operationId: getMenstruation
      tags:
      - Menstruation
      summary: Get menstruation data
      description: Retrieves menstrual cycle and reproductive health data (cycle phases, period days, predicted and actual events, symptoms) for a user over a date range.
      parameters:
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - $ref: '#/components/parameters/ToWebhook'
      responses:
        '200':
          description: Menstruation payload (inline) or acknowledgement (webhook delivery).
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    Unauthorized:
      description: Missing or invalid dev-id / x-api-key credentials.
    RateLimited:
      description: Rate limit exceeded. Terra meters data-read endpoints by a per-user day-budget (days requested = end_date - start_date), not a per-second cap. Response includes X-Terra-RateLimit-* headers and Retry-After.
  parameters:
    EndDate:
      name: end_date
      in: query
      required: false
      schema:
        type: string
      description: End of the date range. Defaults to now if omitted.
    ToWebhook:
      name: to_webhook
      in: query
      required: false
      schema:
        type: boolean
        default: true
      description: When true (default), the payload is fetched asynchronously and streamed to your configured webhook destination instead of returned inline.
    StartDate:
      name: start_date
      in: query
      required: true
      schema:
        type: string
      description: Start of the date range (ISO 8601 date or Unix timestamp).
    UserId:
      name: user_id
      in: query
      required: true
      schema:
        type: string
      description: The Terra user ID to fetch data for.
  securitySchemes:
    devId:
      type: apiKey
      in: header
      name: dev-id
      description: Your public Terra developer identifier.
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your secret Terra API key.