openapi: 3.1.0
info:
  title: ThermalTrace API
  version: 1.2.0
  description: |
    HTTP endpoints for device ingest, share links, metrics, devices CRUD, MQTT bridge, and inbound automations.
    Authenticated dashboard routes use Supabase session cookies; programmatic access uses API keys (Pro).
servers:
  - url: https://thermaltrace.dev
paths:
  /api/ingest/{deviceKey}:
    post:
      summary: Push sensor readings
      parameters:
        - name: deviceKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: Readings accepted
        "401":
          description: Invalid device key
  /api/ingest/mqtt:
    post:
      summary: MQTT-over-HTTP bridge
      parameters:
        - name: X-Ingest-Key
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                topic:
                  type: string
                payload:
                  type: string
                message:
                  type: object
      responses:
        "200":
          description: Forwarded to ingest
  /api/v1/devices:
    get:
      summary: List household devices (Pro API key)
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Device list
    post:
      summary: Create push device (Pro API key)
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                space:
                  type: string
      responses:
        "201":
          description: Device created with one-time ingest_key
  /api/v1/devices/sensors-batch:
    post:
      summary: Batch-update sensor labels and visibility (Pro API key)
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [sensors]
              properties:
                sensors:
                  type: array
                  items:
                    type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                      label:
                        type: string
                      visible:
                        type: boolean
      responses:
        "200":
          description: Sensors updated
  /api/v1/pull-setup:
    post:
      summary: Save pull feeds and probe labels (Pro API key)
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [feeds]
              properties:
                feeds:
                  type: array
                  items:
                    type: object
                    required: [url]
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      url:
                        type: string
                      enabled:
                        type: boolean
                      jsonRoot:
                        type: string
                probes:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      feedId:
                        type: string
                      key:
                        type: string
                      label:
                        type: string
                      visible:
                        type: boolean
      responses:
        "200":
          description: Pull setup saved
  /api/v1/metrics:
    get:
      summary: Prometheus metrics (Pro API key)
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Prometheus text format
  /api/inbound/{token}:
    post:
      summary: Inbound webhook actions (Zapier / Home Assistant)
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum: [snooze, vacation, clear_snooze, clear_vacation, status]
                hours:
                  type: integer
      responses:
        "200":
          description: Action applied
  /api/share/{token}/readings:
    get:
      summary: Public share link readings
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: JSON readings payload
  /api/status/subscribe:
    post:
      summary: Subscribe to system status emails
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
      responses:
        "200":
          description: Subscribed
  /api/push/fcm:
    post:
      summary: Register an FCM device token (Pro, session cookies)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
                platform:
                  type: string
                  enum: [android, ios, web]
                appId:
                  type: string
      responses:
        "200":
          description: Token registered
        "403":
          description: Pro plan required
    delete:
      summary: Unregister an FCM device token
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
      responses:
        "200":
          description: Token removed
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer