openapi: 3.0.3
info:
  title: Terra Activity Daily 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: Daily
  description: Day-level aggregated summaries.
paths:
  /daily:
    get:
      operationId: getDaily
      tags:
      - Daily
      summary: Get daily summary data
      description: Retrieves day-level aggregated summaries (steps, distance, calories, active durations, heart-rate summaries, stress) for a user over a date range.
      parameters:
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - $ref: '#/components/parameters/ToWebhook'
      - $ref: '#/components/parameters/WithSamples'
      responses:
        '200':
          description: Daily 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.
    StartDate:
      name: start_date
      in: query
      required: true
      schema:
        type: string
      description: Start of the date range (ISO 8601 date or Unix timestamp).
    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.
    UserId:
      name: user_id
      in: query
      required: true
      schema:
        type: string
      description: The Terra user ID to fetch data for.
    WithSamples:
      name: with_samples
      in: query
      required: false
      schema:
        type: boolean
      description: Include granular time-series samples in the payload.
  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.