openapi: 3.1.0
info:
  title: ProbeHarbor API
  version: 1.5.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, which need the household owner's plan to include the API (Pro) at the time of each call.
    API keys have a scope: `read` (metrics and the device list; the default for new keys) or `write`
    (also creates devices, edits sensors, replaces the pull setup). Each `/api/v1` operation states the
    scope it needs in `x-required-scope`; a read key on a write operation gets `403` with
    `code: insufficient_scope`. Keys created before scopes existed are `write`.
servers:
  - url: https://probeharbor.dev
paths:
  /api/ingest/{deviceKey}:
    post:
      summary: Push sensor readings
      description: |
        Send the device key either in the path or in the `X-Ingest-Key` header.
        With the header, use `_` as the path segment (`/api/ingest/_`) so the key
        stays out of URLs and logs. If both are present, the header wins.
        New sensor keys are created on the first POST. Values outside physical
        ranges, or known sensor fault codes, are not stored and are listed in
        `rejected`. Timestamps are set by the server.
      parameters:
        - name: deviceKey
          in: path
          required: true
          description: The device key, or `_` when sending it in `X-Ingest-Key`.
          schema:
            type: string
        - name: X-Ingest-Key
          in: header
          required: false
          description: The device key (preferred over the path).
          schema:
            type: string
      requestBody:
        required: true
        description: JSON, at most 65536 bytes. ProbeHarbor, SenML and Home Assistant REST shapes are detected.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: Readings stored
          content:
            application/json:
              schema:
                type: object
                required: [ok, readings, sensors_created]
                properties:
                  ok:
                    type: boolean
                    const: true
                  readings:
                    type: integer
                    description: Number of readings stored
                  sensors_created:
                    type: integer
                    description: Sensors created by this request
                  rejected:
                    type: array
                    description: Present only when some values were not stored
                    items:
                      $ref: "#/components/schemas/RejectedReading"
        "400":
          description: |
            Missing device key, invalid JSON, or no usable sensor values
            (`No sensor values found`, or `No valid sensor values` with `rejected`).
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                  rejected:
                    type: array
                    items:
                      $ref: "#/components/schemas/RejectedReading"
        "401":
          description: Invalid device key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413":
          description: Body larger than 65536 bytes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests for this device key (about 60 per minute; counted per server instance, so approximate)
          headers:
            Retry-After:
              description: Seconds to wait before retrying, when known
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Readings could not be stored; safe to retry
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/ingest/mqtt:
    post:
      summary: MQTT-over-HTTP bridge
      description: |
        Wraps an MQTT message (from a bridge such as Node-RED or an HA automation)
        and forwards its payload to push ingest. `payload` may be a JSON string;
        `message` an already-parsed object. Responses after forwarding are the
        push ingest responses (see `/api/ingest/{deviceKey}`).
      parameters:
        - name: X-Ingest-Key
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        description: JSON, at most 65536 bytes.
        content:
          application/json:
            schema:
              type: object
              properties:
                topic:
                  type: string
                payload:
                  type: string
                  description: JSON string with the readings
                message:
                  type: object
                  description: Readings object (used when payload is absent)
      responses:
        "200":
          description: Forwarded and stored (same body as push ingest 200)
        "400":
          description: Missing X-Ingest-Key header, invalid JSON, invalid payload JSON string, missing payload or message, or no usable sensor values
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Invalid device key
        "413":
          description: Body larger than 65536 bytes
        "429":
          description: Too many requests for this device key
        "500":
          description: Readings could not be stored; safe to retry
  /api/v1/devices:
    get:
      summary: List household devices (Pro API key)
      description: Needs an API key with `read` or `write` scope.
      x-required-scope: read
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Device list
          content:
            application/json:
              schema:
                type: object
                properties:
                  devices:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        source:
                          type: string
                          enum: [push, pull]
                        space:
                          type: [string, "null"]
                        last_seen_at:
                          type: [string, "null"]
                          format: date-time
        "401":
          description: Missing Authorization header, or an unknown or revoked API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The household owner's current plan doesn't include the API (`API access needs a Pro plan`), e.g. after a downgrade. Read and write keys may both call this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: The plan couldn't be checked; try again
        "500":
          description: Devices could not be read
    post:
      summary: Create push device (Pro API key)
      description: Needs an API key with `write` scope (the response includes the device's ingest key).
      x-required-scope: write
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Defaults to "API device"
                space:
                  type: string
                  description: Accepted but currently ignored (set the space in the dashboard).
      responses:
        "201":
          description: Device created. `ingest_key` is shown only here; store it now.
          content:
            application/json:
              schema:
                type: object
                properties:
                  device:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                  ingest_key:
                    type: string
        "400":
          description: Invalid JSON, or the device couldn't be created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing Authorization header, or an unknown or revoked API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: |
            The household owner's current plan doesn't include the API (`API access needs a Pro plan`),
            or the plan's push-device limit is reached (`code: device_limit`, same limit as the dashboard),
            or the API key is read-only and this operation needs a `write` key (`code: insufficient_scope`).
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/InsufficientScopeError"
        "503":
          description: The plan couldn't be checked; try again
  /api/v1/devices/sensors-batch:
    post:
      summary: Batch-update sensor labels and visibility (Pro API key)
      description: |
        Needs an API key with `write` scope. Sensor ids not in the key's household are skipped silently.
      x-required-scope: write
      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 (`{"ok": true}`)'
        "400":
          description: Invalid JSON or no sensors provided
        "401":
          description: Missing Authorization header, or an unknown or revoked API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: |
            The household owner's current plan doesn't include the API (`API access needs a Pro plan`), e.g. after a downgrade,
            or the API key is read-only and this operation needs a `write` key (`code: insufficient_scope`).
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/InsufficientScopeError"
        "503":
          description: The plan couldn't be checked; try again
        "500":
          description: A sensor update failed; earlier rows in the batch may already be saved
  /api/v1/pull-setup:
    post:
      summary: Save pull feeds and probe labels (Pro API key)
      description: |
        Needs an API key with `write` scope. Replaces the pull-feed setup of the key's household.
        Probes whose feedId isn't in `feeds` are dropped.
      x-required-scope: write
      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
        "400":
          description: Invalid JSON or no valid feeds (each feed needs a url)
        "401":
          description: Missing Authorization header, or an unknown or revoked API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: |
            The household owner's current plan doesn't include the API (`API access needs a Pro plan`), e.g. after a downgrade,
            or the API key is read-only and this operation needs a `write` key (`code: insufficient_scope`).
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/Error"
                  - $ref: "#/components/schemas/InsufficientScopeError"
        "503":
          description: The plan couldn't be checked; try again
        "404":
          description: The household has no owner
        "500":
          description: The setup couldn't be saved
  /api/v1/metrics:
    get:
      summary: Prometheus metrics (Pro API key)
      description: Needs an API key with `read` or `write` scope.
      x-required-scope: read
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Prometheus text format
          content:
            text/plain:
              schema:
                type: string
        "401":
          description: Missing Authorization header, or an unknown or revoked API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The household owner's current plan doesn't include the API (`API access needs a Pro plan`), e.g. after a downgrade. Read and write keys may both call this operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: The plan couldn't be checked; try again
  /api/inbound/{token}:
    post:
      summary: Inbound webhook actions (Zapier / Home Assistant)
      description: |
        Every request must be signed with the webhook's signing secret:
        `X-ProbeHarbor-Timestamp` (Unix seconds) and
        `X-ProbeHarbor-Signature-V2: sha256=<hex HMAC-SHA256 of "<timestamp>.<raw body>">`;
        timestamps more than 5 minutes off are rejected. The older body-only
        signature (`X-ProbeHarbor-Signature`, `X-ThermalTrace-Signature`,
        `X-GarageTemp-Signature`, `X-Signature`) is no longer accepted (since
        2026-11-11); a request sending only that gets `401` with an error
        starting `Signature V2 required`. The action can also come from `?action=`.

        `snooze` / `vacation` (and their clears) act on **this webhook's household
        only**: they hold that household's routine alerts for all its members,
        exactly like a member's own snooze / vacation (freeze, leak, power and
        offline alerts still send). They don't change members' own alert
        settings, and don't hold a member's alerts for their other households.
        `snooze` takes 1-168 hours (default 24), `vacation` 1-90 days (default 7).
        A new `snooze` / `vacation` replaces the household's previous end time.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
        - name: action
          in: query
          required: false
          schema:
            type: string
            enum: [snooze, vacation, clear_snooze, clear_vacation, status]
        - name: X-ProbeHarbor-Timestamp
          in: header
          required: true
          schema:
            type: string
        - name: X-ProbeHarbor-Signature-V2
          in: header
          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
                  description: snooze length (default 24)
                days:
                  type: integer
                  description: vacation length (default 7)
      responses:
        "200":
          description: Action applied (snooze, vacation, clears), household status (`status`), or a help message for an unknown action
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  action:
                    type: string
                  members:
                    type: integer
                    description: |
                      snooze / vacation / clears: how many members the household has
                      (whose alerts for this household the hold affects)
                  alertHold:
                    type: object
                    description: "`status` only: this household's hold set by the inbound webhook. Members' own snoozes aren't included."
                    properties:
                      snoozedUntil:
                        type: [string, "null"]
                        format: date-time
                        description: When the household snooze ends; null when none is active
                      vacationUntil:
                        type: [string, "null"]
                        format: date-time
                        description: When the household vacation ends; null when none is active
                  message:
                    type: string
        "400":
          description: Missing token
        "401":
          description: Invalid webhook token, invalid signature, or a stale timestamp (`Stale timestamp …`)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/share/{token}/readings:
    get:
      summary: Public share link readings
      description: |
        No login: the token is the credential. Metrics-scoped links default to
        Prometheus text; other links default to JSON. `history` links also
        include 7 days of chart points.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
        - name: format
          in: query
          required: false
          description: "`prometheus` or `grafana` need a metrics-scoped link; anything else returns JSON."
          schema:
            type: string
            enum: [json, prometheus, grafana]
      responses:
        "200":
          description: Readings (JSON), Prometheus text exposition, or Grafana JSON
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
            text/plain:
              schema:
                type: string
        "400":
          description: Missing token
        "403":
          description: "`prometheus`/`grafana` requested on a link that isn't metrics-scoped"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Unknown, revoked or expired link
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests
          headers:
            Retry-After:
              schema:
                type: integer
  /api/status/subscribe:
    post:
      summary: Subscribe to system status emails
      description: |
        HTML form endpoint used by /system-status (not a JSON API). Always answers
        with a redirect back to `/system-status` (or `/<locale>/system-status`)
        carrying the result in the query string: `subscribed=1`, or
        `status_error=rate_limited | verification | invalid_email`. Subscriptions
        are confirmed by email (double opt-in). Needs a Cloudflare Turnstile token.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [email, cf-turnstile-response]
              properties:
                email:
                  type: string
                  format: email
                locale:
                  type: string
                  enum: [en, de, es, fr, pt-br]
                  description: Language of the confirmation email and the page redirected to
                cf-turnstile-response:
                  type: string
                company:
                  type: string
                  description: Honeypot; leave empty
      responses:
        "302":
          description: Redirect to the status page with `subscribed=1` or `status_error=…`
          headers:
            Location:
              schema:
                type: string
  /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
                  minLength: 20
                platform:
                  type: string
                  enum: [android, ios, web]
                  default: android
                appId:
                  type: string
      responses:
        "200":
          description: Token registered (moved from any other account that had it)
        "400":
          description: Invalid JSON, token missing or too short, or unknown platform
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Not signed in
        "403":
          description: Pro plan required
        "500":
          description: The token couldn't be saved
    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
        "400":
          description: Invalid JSON or missing token
        "401":
          description: Not signed in
components:
  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
    InsufficientScopeError:
      type: object
      description: A read-only API key called an operation that needs a `write` key.
      required: [error, code, required_scope]
      properties:
        ok:
          type: boolean
          const: false
          description: Present on operations whose other errors also carry `ok`.
        error:
          type: string
        code:
          type: string
          const: insufficient_scope
        required_scope:
          type: string
          enum: [read, write]
    RejectedReading:
      type: object
      required: [key, kind, value, reason]
      properties:
        key:
          type: string
        kind:
          type: string
        value:
          type: number
        reason:
          type: string
          enum: [sensor_fault, out_of_range]
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        A dashboard API key (`gtm_…`, Dashboard → Share → API). Scope `read` (default) or `write`;
        see each operation's `x-required-scope`.
