Sageox Firmware OTA API

openapi: 3.2.0
info:
  title: SageOx Firmware OTA API
  version: 1.0.0
  description: '# API Reference


    ## Overview


    SageOx is a platform that captures team knowledge from discussions, decisions, and work context into a Ledger (per-repo historical record) and Team Context (team-wide shared knowledge).'
  contact:
    name: SageOx Team
  license:
    name: MIT
servers:
- url: http://localhost:3000
  description: Devcontainer
- url: https://test.sageox.ai
  description: Test
- url: https://sageox.ai
  description: Production
security:
- bearerAuth: []
tags:
- name: Firmware OTA
paths:
  /api/v1/firmware/latest:
    get:
      operationId: getFirmwareManifest
      summary: Check for firmware updates
      description: 'Device-facing endpoint that returns the latest available firmware manifest

        for the specified device type. The device polls this endpoint periodically

        and compares the returned version against its current firmware.


        This endpoint is **unauthenticated** (devices have no JWT) but rate-limited

        by X-Device-ID header. Returns 204 No Content when no update is available.


        The response `url` field contains a pre-signed S3 URL (15-minute TTL) for

        direct firmware binary download. The device fetches this URL directly with

        no auth headers.'
      tags:
      - Firmware OTA
      security: []
      parameters:
      - name: device
        in: query
        required: true
        description: Hardware type identifier (e.g., `scribe`, `clip`).
        schema:
          type: string
          example: scribe
      - name: version
        in: query
        required: true
        description: Currently running firmware version (semver format).
        schema:
          type: string
          example: 1.0.0
      - name: channel
        in: query
        required: false
        description: Release channel to check. Defaults to `stable`.
        schema:
          type: string
          default: stable
          enum:
          - stable
          - early-access
          - beta
          - nightly
      - name: X-Device-ID
        in: header
        required: false
        description: Hardware-derived stable identifier. For scribe, this is the 12-character lowercase hex of the ESP32 base MAC address.
        schema:
          type: string
          example: aabbccddeeff
      - name: X-Device-Type
        in: header
        description: Hardware type, same as the `device` query parameter. Informational.
        schema:
          type: string
          example: scribe
      - name: User-Agent
        in: header
        description: Device firmware user agent string.
        schema:
          type: string
          example: sageox-scribe/1.0.0 (esp32-s3; xtensa-lx7)
      responses:
        '200':
          description: A newer firmware version is available.
          content:
            application/json:
              schema:
                type: object
                required:
                - version
                - url
                description: 'Firmware manifest returned to devices. Field sizes are constrained by

                  the ESP32 firmware parser buffer sizes.

                  '
                properties:
                  version:
                    type: string
                    description: Semver version string. Must be newer than the device's current version.
                    maxLength: 31
                    example: 1.2.0
                  url:
                    type: string
                    description: Pre-signed S3 URL for direct firmware binary download (15-minute TTL, no auth required).
                    maxLength: 511
                  sha256:
                    type: string
                    description: SHA-256 hash of the firmware binary, lowercase hex.
                    pattern: ^[0-9a-f]{64}$
                    example: a3f1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
                  signature:
                    type: string
                    description: Base64-encoded RSA-2048 signature over the SHA-256 digest. Required for production builds.
                    maxLength: 511
                  size:
                    type: integer
                    format: int64
                    description: Firmware binary size in bytes. Used for progress bar and hash verification.
                  changelog:
                    type: string
                    description: Human-readable changelog. Devices with small screens truncate on their end.
                    maxLength: 2048
                  release_date:
                    type: string
                    format: date
                    description: ISO-8601 release date.
                  min_version:
                    type: string
                    description: Security floor. Devices below this version get a forced update (no skip option).
                    maxLength: 31
        '204':
          description: No update available. Device is up to date or not targeted.
        '400':
          description: Missing required query parameters.
        '429':
          description: Rate limit exceeded. Back off and retry.
        '500':
          description: Server error.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT token obtained from the auth service (/api/auth/token).

        Token is validated using JWKS from the auth service.

        Required claims: sub (user_id), email, name, tier.

        '