openapi.yaml

openapi: 3.0.3
info:
  title: hackrf-logger API
  version: "1.0.0"
  description: |
    HTTP API of `hackrf-logger`: a continuous 5 GHz Wi-Fi spectrum logger.

    The service sweeps the spectrum with a HackRF One, keeps a bounded in-memory
    ring of recent frames for the live dashboard, and (optionally) persists frames
    to SQLite. It is **domain-agnostic**: external tools mark generic *capture*
    windows over the spectrum log and later pull the frames inside them.

    All endpoints live under `/api/v1` and return JSON. Errors use
    `{"error": "..."}`. Responses are sent with `Cache-Control: no-store`.

    ## Authentication
    Mutating capture endpoints (create / close / delete) may require a bearer token
    when the server is started with `-api-token <token>`. Read endpoints are always
    open. When no token is configured, the `Authorization` header is ignored.

    ## Persistence
    When started with an empty `-db`, persistence is disabled: capture and history
    endpoints return `503 Service Unavailable`, and `/api/v1/health` reports
    `persistence: false`.
servers:
  - url: http://localhost:8080
    description: Default local dashboard address (-addr :8080)

tags:
  - name: dashboard
  - name: live
  - name: history
  - name: captures

paths:
  /:
    get:
      tags: [dashboard]
      summary: Live spectrum dashboard
      description: Self-contained HTML/JS/canvas dashboard (no external dependencies).
      responses:
        "200":
          description: HTML dashboard
          content:
            text/html:
              schema:
                type: string

  /api/v1/health:
    get:
      tags: [live]
      summary: Liveness probe
      responses:
        "200":
          description: Service is up.
          content:
            application/json:
              schema:
                type: object
                required: [ok, timeMs, persistence]
                properties:
                  ok:
                    type: boolean
                    example: true
                  timeMs:
                    type: integer
                    format: int64
                    description: Server time in Unix milliseconds.
                  persistence:
                    type: boolean
                    description: Whether SQLite persistence is enabled.

  /api/v1/status:
    get:
      tags: [live]
      summary: Device and capture status
      responses:
        "200":
          description: Current device, configuration, and sweep statistics.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"

  /api/v1/frame:
    get:
      tags: [live]
      summary: Latest spectrum frame
      description: |
        The frequency axis (`freqs`) is always present. `seq`, `t`, and `powers`
        are present only once at least one frame has been produced.
      responses:
        "200":
          description: Latest frame plus the frequency axis.
          content:
            application/json:
              schema:
                type: object
                required: [freqs]
                properties:
                  freqs:
                    type: array
                    description: Bin center frequencies in Hz.
                    items:
                      type: number
                      format: double
                  seq:
                    type: integer
                    format: int64
                    description: Monotonic sequence number of the frame.
                  t:
                    type: integer
                    format: int64
                    description: Frame timestamp in Unix milliseconds.
                  powers:
                    type: array
                    description: Power per bin in dB, parallel to `freqs`.
                    items:
                      type: number
                      format: double

  /api/v1/waterfall:
    get:
      tags: [live]
      summary: Incremental waterfall snapshot
      description: Frequency axis, dynamic range, and frames newer than `since`.
      parameters:
        - name: since
          in: query
          required: false
          description: Return only frames with a sequence number greater than this.
          schema:
            type: integer
            format: int64
            default: 0
      responses:
        "200":
          description: Snapshot of recent frames.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Snapshot"

  /api/v1/history:
    get:
      tags: [history]
      summary: Decimated historical frames from SQLite
      parameters:
        - name: from
          in: query
          description: Window start in Unix milliseconds (0 = unbounded).
          schema: { type: integer, format: int64, default: 0 }
        - name: to
          in: query
          description: Window end in Unix milliseconds (0 = now).
          schema: { type: integer, format: int64, default: 0 }
        - name: step
          in: query
          description: Decimation step (return every Nth frame; <=1 returns all).
          schema: { type: integer, default: 0 }
        - name: session
          in: query
          description: Session id to query (0 = current session).
          schema: { type: integer, format: int64, default: 0 }
      responses:
        "200":
          description: Frames in the requested window.
          content:
            application/json:
              schema:
                type: object
                required: [session, freqs, frames]
                properties:
                  session:
                    type: integer
                    format: int64
                  freqs:
                    type: array
                    items: { type: number, format: double }
                  frames:
                    type: array
                    items:
                      $ref: "#/components/schemas/HistFrame"
        "404":
          description: No session exists yet.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "500":
          description: Query error.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "503":
          description: Persistence disabled.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }

  /api/v1/captures:
    post:
      tags: [captures]
      summary: Create a capture window
      description: |
        Marks a time window over the spectrum log. The window's start may be in the
        recent past (`startMs`, or `now - preRollMs`); the logger backfills that span
        from its in-memory ring and records at full rate while the capture is open.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CaptureRequest"
      responses:
        "201":
          description: Capture created.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Capture" }
        "400":
          description: Invalid request body or capture parameters.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401":
          description: Missing or invalid bearer token.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "409":
          description: No active capture session yet (no frames produced).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
    get:
      tags: [captures]
      summary: List capture windows
      parameters:
        - name: code
          in: query
          description: Filter by freeform code tag.
          schema: { type: string }
        - name: status
          in: query
          description: Filter by status.
          schema:
            type: string
            enum: [open, closed]
        - name: limit
          in: query
          description: Maximum number of captures to return (0 = no limit).
          schema: { type: integer, default: 0 }
      responses:
        "200":
          description: Captures matching the filter, newest first.
          content:
            application/json:
              schema:
                type: object
                required: [captures]
                properties:
                  captures:
                    type: array
                    items: { $ref: "#/components/schemas/Capture" }
        "500":
          description: Query error.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }

  /api/v1/captures/{id}:
    parameters:
      - $ref: "#/components/parameters/CaptureId"
    get:
      tags: [captures]
      summary: Get one capture
      responses:
        "200":
          description: The capture.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Capture" }
        "400":
          description: Invalid capture id.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "404":
          description: Capture not found.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
    delete:
      tags: [captures]
      summary: Delete a capture marker
      description: Removes the capture marker; the underlying frames are kept.
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Deleted.
        "400":
          description: Invalid capture id.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401":
          description: Missing or invalid bearer token.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "404":
          description: Capture not found.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }

  /api/v1/captures/{id}/close:
    parameters:
      - $ref: "#/components/parameters/CaptureId"
    post:
      tags: [captures]
      summary: Finalize or schedule the end of a capture
      description: |
        Sets the capture's end (default now) plus an optional `postRollMs` tail.
        If the resulting end is already in the past, the capture is closed
        immediately; otherwise it keeps recording until the background finalizer
        reaches the end. Idempotent on already-closed captures.
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CaptureCloseRequest" }
      responses:
        "200":
          description: Updated capture.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Capture" }
        "400":
          description: Invalid request.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401":
          description: Missing or invalid bearer token.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "404":
          description: Capture not found.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }

  /api/v1/captures/{id}/frames:
    parameters:
      - $ref: "#/components/parameters/CaptureId"
    get:
      tags: [captures]
      summary: Frames inside a capture window
      description: |
        Returns the capture plus the frames in its window. If the capture has focus
        ranges and `full` is not set, only the bins within those ranges are returned.
      parameters:
        - name: step
          in: query
          description: Decimation step (return every Nth frame; <=1 returns all).
          schema: { type: integer, default: 0 }
        - name: full
          in: query
          description: Set to `1` to return the full band instead of just the focus ranges.
          schema:
            type: string
            enum: ["0", "1"]
            default: "0"
      responses:
        "200":
          description: Capture and its frames.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CaptureFrames" }
        "400":
          description: Invalid capture id.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "404":
          description: Capture not found.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }

  /api/v1/captures/{id}/export:
    parameters:
      - $ref: "#/components/parameters/CaptureId"
    get:
      tags: [captures]
      summary: Download a self-contained capture bundle
      description: |
        Same data as `/frames`, plus `binWidthHz` and `exportedMs`, served with a
        `Content-Disposition: attachment; filename=capture-<id>.json` header.
      parameters:
        - name: step
          in: query
          schema: { type: integer, default: 0 }
        - name: full
          in: query
          schema:
            type: string
            enum: ["0", "1"]
            default: "0"
      responses:
        "200":
          description: Downloadable capture bundle.
          headers:
            Content-Disposition:
              description: Attachment filename.
              schema: { type: string }
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/CaptureFrames"
                  - type: object
                    required: [binWidthHz, exportedMs]
                    properties:
                      binWidthHz:
                        type: number
                        format: double
                      exportedMs:
                        type: integer
                        format: int64
        "400":
          description: Invalid capture id.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "404":
          description: Capture not found.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Required only when the server is started with `-api-token`. Send as
        `Authorization: Bearer <token>`.

  parameters:
    CaptureId:
      name: id
      in: path
      required: true
      description: Capture id (positive integer).
      schema:
        type: integer
        format: int64
        minimum: 1

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string

    Status:
      type: object
      properties:
        serial: { type: string }
        board: { type: string }
        firmware: { type: string }
        freqMinHz: { type: integer, format: int64 }
        freqMaxHz: { type: integer, format: int64 }
        binWidthHz: { type: number, format: double }
        numBins: { type: integer }
        lna: { type: integer }
        vga: { type: integer }
        amp: { type: boolean }
        sessionId: { type: integer, format: int64 }
        frames: { type: integer, format: int64, minimum: 0 }
        sweepsPerSec: { type: number, format: double }
        dropped: { type: integer, format: int64, minimum: 0 }
        streaming: { type: boolean }
        uptimeSec: { type: number, format: double }

    FreqRange:
      type: object
      description: Inclusive frequency band in Hz.
      required: [lowHz, highHz]
      properties:
        lowHz: { type: integer, format: int64 }
        highHz: { type: integer, format: int64 }

    RingFrame:
      type: object
      required: [seq, t, powers]
      properties:
        seq:
          type: integer
          format: int64
          minimum: 0
          description: Monotonic sequence number.
        t:
          type: integer
          format: int64
          description: Timestamp in Unix milliseconds.
        powers:
          type: array
          items: { type: number, format: double }
          description: Power per bin in dB.

    HistFrame:
      type: object
      required: [t, powers]
      properties:
        t:
          type: integer
          format: int64
          description: Timestamp in Unix milliseconds.
        powers:
          type: array
          items: { type: number, format: double }
          description: Power per bin in dB.

    Snapshot:
      type: object
      required: [freqs, minDb, maxDb, seq, frames, numBins]
      properties:
        freqs:
          type: array
          items: { type: number, format: double }
          description: Bin center frequencies in Hz.
        minDb: { type: number, format: double }
        maxDb: { type: number, format: double }
        seq:
          type: integer
          format: int64
          minimum: 0
          description: Highest sequence number included.
        frames:
          type: array
          items: { $ref: "#/components/schemas/RingFrame" }
        numBins: { type: integer }

    Capture:
      type: object
      required: [id, sessionId, status, startMs, createdMs]
      properties:
        id: { type: integer, format: int64 }
        sessionId: { type: integer, format: int64 }
        label: { type: string }
        code: { type: string }
        status:
          type: string
          enum: [open, closed]
          description: '"open" while recording, "closed" once finalized.'
        startMs: { type: integer, format: int64 }
        endMs:
          type: integer
          format: int64
          nullable: true
          description: Scheduled or actual end in Unix ms; null while open-ended.
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Arbitrary caller JSON, echoed back verbatim.
        focus:
          type: array
          items: { $ref: "#/components/schemas/FreqRange" }
          description: Frequency ranges retrieval is restricted to (unless full=1).
        createdMs: { type: integer, format: int64 }

    CaptureRequest:
      type: object
      description: All fields optional. Start defaults to now minus preRollMs.
      properties:
        label: { type: string }
        code: { type: string }
        startMs:
          type: integer
          format: int64
          nullable: true
          description: Explicit start; overrides preRollMs-based start.
        endMs:
          type: integer
          format: int64
          nullable: true
          description: One-shot window end; omit to keep the capture open.
        preRollMs:
          type: integer
          format: int64
          description: Backfill this many ms before now when startMs is omitted.
        postRollMs:
          type: integer
          format: int64
          description: Extra recording appended after endMs.
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Arbitrary caller JSON, echoed back on reads.
        focusRanges:
          type: array
          items: { $ref: "#/components/schemas/FreqRange" }
          description: Restrict frame/export retrieval to these bands.

    CaptureCloseRequest:
      type: object
      properties:
        endMs:
          type: integer
          format: int64
          nullable: true
          description: End time (default now).
        postRollMs:
          type: integer
          format: int64
          description: Keep recording this much longer past the end.

    CaptureFrames:
      type: object
      required: [capture, freqs, frames]
      properties:
        capture: { $ref: "#/components/schemas/Capture" }
        freqs:
          type: array
          items: { type: number, format: double }
        frames:
          type: array
          items: { $ref: "#/components/schemas/HistFrame" }