openapi: 3.1.0
info:
  title: Spike Application User API
  description: >-
    Spike (Spike Technologies) unified health and wearables data API. A single
    integration layer that connects an application to 500+ wearables, IoT
    devices, CGMs, EMRs, labs, and nutrition sources - Apple Health, Garmin,
    Fitbit, Oura, Whoop, Dexcom, FreeStyle Libre, Withings, Polar, Suunto,
    Strava, and more. Applications authenticate their end users with HMAC
    signatures to mint a JWT access token, connect providers through hosted
    integration flows, then query normalized health data (sleep, workouts, time
    series, statistics), analyze nutrition and lab reports, and receive
    record-change webhooks.


    This document is grounded in Spike's published OpenAPI (v3.0.2) and public
    documentation at https://docs.spikeapi.com. Path, method, base URL, auth, and
    provider surfaces are confirmed from the official OpenAPI. Request and
    response schemas are modeled generically here where full component schemas
    were not enumerated - see endpointsModeled notes in review.yml.
  version: 3.0.2
  contact:
    name: Spike Technologies
    url: https://www.spikeapi.com
servers:
  - url: https://app-api.spikeapi.com/v3
    description: Spike Application User API
security:
  - bearer: []
tags:
  - name: Auth
    description: Authenticate end users and mint JWT access tokens.
  - name: Provider Integrations
    description: Connect and disconnect a user's health data providers.
  - name: Provider Records
    description: Query normalized provider health data records.
  - name: Sleep
    description: Query normalized sleep sessions and stages.
  - name: Workouts
    description: Query normalized workouts and physical activities.
  - name: Time Series
    description: Query high-resolution metric time series.
  - name: Statistics
    description: Query aggregated statistics for metrics over time.
  - name: Nutrition AI
    description: Analyze and manage nutrition records.
  - name: Lab Reports
    description: Upload and query structured lab report biomarkers.
  - name: Users
    description: Current user, user properties, and application info.
  - name: SDK Push
    description: Ingest on-device health data pushed from the mobile SDKs.
paths:
  /auth/hmac:
    post:
      operationId: authHmac
      tags:
        - Auth
      summary: Authenticate with an HMAC signature
      description: >-
        Exchange an HMAC-SHA256 signature (the application user ID signed with
        the application secret) for a JWT access token. No pre-registration is
        required; users are provisioned on first authentication.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HmacAuthRequest'
      responses:
        '200':
          description: A JWT access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/client_token:
    post:
      operationId: authClientToken
      tags:
        - Auth
      summary: Authenticate with a client token
      description: Mint an access token using an application-level client token grant.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: A JWT access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/pkcs1:
    post:
      operationId: authPkcs1
      tags:
        - Auth
      summary: Authenticate with a PKCS1 signature
      description: Exchange an RSA PKCS1 signature for a JWT access token.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: A JWT access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicationinfo:
    get:
      operationId: getApplicationInfo
      tags:
        - Users
      summary: Application Information
      description: Returns application-level configuration and the list of available providers.
      responses:
        '200':
          description: Application information.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /userinfo:
    get:
      operationId: getUserInfo
      tags:
        - Users
      summary: User Information
      description: Returns the current authenticated user, including connected provider integrations.
      responses:
        '200':
          description: User information.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /userproperties:
    get:
      operationId: getUserProperties
      tags:
        - Users
      summary: User Properties
      description: Returns properties associated with the current user.
      responses:
        '200':
          description: User properties.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /providers/{provider_slug}/integration/init:
    parameters:
      - $ref: '#/components/parameters/ProviderSlug'
    get:
      operationId: initProviderIntegration
      tags:
        - Provider Integrations
      summary: Initialize a provider integration
      description: >-
        Start the hosted integration flow for a provider (for example garmin,
        fitbit, oura, whoop, dexcom, withings). Redirects the user into the
        provider's OAuth-style consent screen.
      responses:
        '302':
          description: Redirect to the provider authorization screen.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /providers/{provider_slug}/integration/init_url:
    parameters:
      - $ref: '#/components/parameters/ProviderSlug'
    get:
      operationId: getProviderIntegrationInitUrl
      tags:
        - Provider Integrations
      summary: Get a provider integration init URL
      description: Returns the URL that begins the hosted integration flow for a provider, for embedding in your own UI.
      responses:
        '200':
          description: The integration initialization URL.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /providers/{provider_slug}/integration:
    parameters:
      - $ref: '#/components/parameters/ProviderSlug'
    delete:
      operationId: deleteProviderIntegration
      tags:
        - Provider Integrations
      summary: Delete a provider integration
      description: Disconnects a provider from the current user and removes the stored authorization.
      responses:
        '200':
          description: The integration was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /providers/{provider_slug}/integration/callback:
    parameters:
      - $ref: '#/components/parameters/ProviderSlug'
    get:
      operationId: providerIntegrationCallback
      tags:
        - Provider Integrations
      summary: Provider OAuth callback
      description: >-
        OAuth redirect callback endpoint hit by the provider after the user
        authorizes access. Each provider also has an explicit callback path
        (for example /providers/garmin/integration/callback,
        /providers/fitbit/integration/callback,
        /providers/dexcom/integration/callback).
      security: []
      responses:
        '302':
          description: Redirect back into the application after linking.
  /queries/provider_records:
    get:
      operationId: listProviderRecords
      tags:
        - Provider Records
      summary: List Provider Records
      description: Lists normalized provider records for the user, filtered by time range, provider, and metric.
      parameters:
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/ProviderQuery'
        - $ref: '#/components/parameters/Metric'
      responses:
        '200':
          description: A list of provider records.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queries/provider_records/{record_id}:
    parameters:
      - $ref: '#/components/parameters/RecordId'
    get:
      operationId: getProviderRecord
      tags:
        - Provider Records
      summary: Get Provider Record
      description: Retrieves a single normalized provider record by ID, including its metrics.
      responses:
        '200':
          description: A provider record.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /queries/provider_record:
    post:
      operationId: queryProviderRecordCompat
      tags:
        - Provider Records
      summary: 'COMPAT: Query provider records'
      description: Compatibility endpoint that queries provider records via a POST body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Matching provider records.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queries/sleeps:
    get:
      operationId: listSleeps
      tags:
        - Sleep
      summary: List Sleeps
      description: Lists normalized sleep sessions with stage breakdowns, duration, and efficiency.
      parameters:
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: A list of sleep sessions.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queries/sleeps/{sleep_id}:
    parameters:
      - name: sleep_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getSleep
      tags:
        - Sleep
      summary: Get Sleep
      description: Retrieves a single sleep session by ID with full stage data.
      responses:
        '200':
          description: A sleep session.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /queries/workouts:
    get:
      operationId: listWorkouts
      tags:
        - Workouts
      summary: List Workouts
      description: Lists normalized workouts / physical activities with per-activity metrics.
      parameters:
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: A list of workouts.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queries/workouts/{workout_id}:
    parameters:
      - name: workout_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getWorkout
      tags:
        - Workouts
      summary: Get Workout
      description: Retrieves a single workout by ID with full metric detail.
      responses:
        '200':
          description: A workout.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /queries/timeseries:
    get:
      operationId: queryTimeSeries
      tags:
        - Time Series
      summary: Time Series
      description: >-
        Returns a time series for a specified metric (for example heartrate,
        heartrate_resting, hrv_rmssd, hrv_sdnn, glucose, weight, body_fat, spo2,
        breathing_rate, steps, distance, calories_burned) over a time range.
      parameters:
        - $ref: '#/components/parameters/Metric'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: A metric time series.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queries/timeseries/samples:
    get:
      operationId: queryTimeSeriesSamples
      tags:
        - Time Series
      summary: Get Samples Time Series
      description: Returns raw sample-level time series data for a metric.
      parameters:
        - $ref: '#/components/parameters/Metric'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: Sample-level time series.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queries/timeseries/split:
    get:
      operationId: queryTimeSeriesSplit
      tags:
        - Time Series
      summary: Time Series Data split by provider source
      description: Returns time series data for a metric split out per contributing provider source.
      parameters:
        - $ref: '#/components/parameters/Metric'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: Time series split by provider.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queries/statistics/daily:
    get:
      operationId: queryStatisticsDaily
      tags:
        - Statistics
      summary: Daily Statistics
      description: Returns daily aggregated statistics for a metric over a time range.
      parameters:
        - $ref: '#/components/parameters/Metric'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: Daily statistics.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queries/statistics/interval:
    get:
      operationId: queryStatisticsInterval
      tags:
        - Statistics
      summary: Interval Statistics
      description: Returns statistics aggregated over a specified interval.
      parameters:
        - $ref: '#/components/parameters/Metric'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: Interval statistics.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queries/statistics/interpolation:
    get:
      operationId: queryStatisticsInterpolation
      tags:
        - Statistics
      summary: Statistics by interpolation
      description: Returns interpolated statistics for a metric where gaps are filled between samples.
      parameters:
        - $ref: '#/components/parameters/Metric'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: Interpolated statistics.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /nutrition_records:
    get:
      operationId: listNutritionRecords
      tags:
        - Nutrition AI
      summary: List nutrition records
      description: Lists nutrition records for the user over a time range.
      parameters:
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: A list of nutrition records.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /nutrition_records/image:
    post:
      operationId: analyzeNutritionImage
      tags:
        - Nutrition AI
      summary: Analyze a food image
      description: Analyzes a base64 food image and returns a structured nutrition record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The analyzed nutrition record.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /nutrition_records/ingredients/label:
    post:
      operationId: analyzeNutritionLabel
      tags:
        - Nutrition AI
      summary: Analyze a nutrition-facts label
      description: Analyzes a nutrition-facts label image and returns structured nutrition fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The analyzed nutrition record.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /nutrition_records/text:
    post:
      operationId: analyzeNutritionText
      tags:
        - Nutrition AI
      summary: Analyze a free-text meal
      description: Analyzes a free-text meal description and returns a structured nutrition record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The analyzed nutrition record.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /nutrition_records/manual:
    post:
      operationId: createManualNutritionRecord
      tags:
        - Nutrition AI
      summary: Upload a manual nutrition record
      description: Creates a nutrition record from manually supplied fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The created nutrition record.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /nutrition_records/{nutrition_record_id}:
    parameters:
      - name: nutrition_record_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getNutritionRecord
      tags:
        - Nutrition AI
      summary: Get a nutrition record
      description: Retrieves a nutrition record by ID.
      responses:
        '200':
          description: The nutrition record.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: modifyNutritionRecord
      tags:
        - Nutrition AI
      summary: Modify a nutrition record
      description: Adjusts a nutrition record, for example changing portion size.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The updated nutrition record.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: replaceNutritionRecord
      tags:
        - Nutrition AI
      summary: Replace a nutrition record
      description: Replaces an existing nutrition record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The replaced nutrition record.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteNutritionRecord
      tags:
        - Nutrition AI
      summary: Delete a nutrition record
      description: Removes a nutrition record.
      responses:
        '200':
          description: The record was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /lab_reports:
    get:
      operationId: listLabReports
      tags:
        - Lab Reports
      summary: List lab reports
      description: Lists lab reports for the user over a time range.
      parameters:
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: A list of lab reports.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: uploadLabReport
      tags:
        - Lab Reports
      summary: Upload a lab report
      description: Uploads a base64-encoded lab report document for AI extraction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The uploaded lab report.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /lab_reports/process:
    post:
      operationId: processLabReport
      tags:
        - Lab Reports
      summary: Process a lab report
      description: Triggers or re-triggers AI processing of an uploaded lab report document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The processing result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /lab_reports/{lab_report_id}:
    parameters:
      - name: lab_report_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getLabReport
      tags:
        - Lab Reports
      summary: Get a lab report
      description: Retrieves a lab report by ID with structured biomarker results.
      responses:
        '200':
          description: The lab report.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound'
  /providers/apple/push:
    post:
      operationId: pushAppleHealth
      tags:
        - SDK Push
      summary: Push Apple Health data
      description: Ingests Apple Health samples pushed from the Spike iOS SDK (JSON).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Data accepted for normalization.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /providers/health_connect/push:
    post:
      operationId: pushHealthConnect
      tags:
        - SDK Push
      summary: Push Android Health Connect data
      description: Ingests Android Health Connect samples pushed from the Spike Android SDK (JSON).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Data accepted for normalization.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /providers/samsung_health_data/push/proto:
    post:
      operationId: pushSamsungHealth
      tags:
        - SDK Push
      summary: Push Samsung Health data (protobuf)
      description: Ingests Samsung Health samples pushed from the Spike SDK as protobuf.
      requestBody:
        required: true
        content:
          application/x-protobuf:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Data accepted for normalization.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    ProviderSlug:
      name: provider_slug
      in: path
      required: true
      description: >-
        Provider identifier, for example garmin, fitbit, oura, whoop, dexcom,
        freestyle_libre, withings, polar, suunto, strava, coros, wahoo,
        ultrahuman, omron_us, omron_eu, huawei, google_fit, google_health,
        biostrap, luna, map_my_fitness.
      schema:
        type: string
    RecordId:
      name: record_id
      in: path
      required: true
      schema:
        type: string
    StartTime:
      name: start_time
      in: query
      required: false
      description: Start of the query window (ISO 8601).
      schema:
        type: string
        format: date-time
    EndTime:
      name: end_time
      in: query
      required: false
      description: End of the query window (ISO 8601).
      schema:
        type: string
        format: date-time
    ProviderQuery:
      name: provider
      in: query
      required: false
      description: Filter results to a specific provider slug.
      schema:
        type: string
    Metric:
      name: metric
      in: query
      required: false
      description: >-
        Metric identifier - for example heartrate, heartrate_resting, hrv_rmssd,
        hrv_sdnn, glucose, weight, body_fat, spo2, breathing_rate, steps,
        distance, calories_burned, sleep_duration, sleep_efficiency.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    HmacAuthRequest:
      type: object
      required:
        - application_id
        - application_user_id
        - signature
      properties:
        application_id:
          type: string
          description: The application ID from the Spike admin console.
        application_user_id:
          type: string
          maxLength: 128
          description: >-
            Your identifier for the end user (max 128 chars; alphanumeric plus
            - _ .).
        signature:
          type: string
          description: HMAC-SHA256 of the application_user_id signed with the application secret.
    AuthToken:
      type: object
      properties:
        access_token:
          type: string
          description: JWT access token to send as a Bearer credential.
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Token lifetime in seconds.
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string