openapi: 3.0.3
info:
  title: NASdisks Drive Data API
  description: >-
    Free, CORS-enabled, read-only API for NAS hard-drive data: full
    specifications, CMR/SMR recording-technology classification (judged per
    model, not per family), acoustic noise figures, and real-world annualized
    failure rates derived from Backblaze Drive Stats. Also exposes a region-aware
    "cheapest $/TB" feed used by the embeddable price widget.


    Licensing is scoped: the drive specs and CMR/SMR classification are published
    by nasdisks.com under CC BY 4.0. The reliability fields (afr_pct and the
    reliability_* counts) come from Backblaze Drive Stats and remain under
    Backblaze's terms - free to use with attribution to Backblaze, but the data
    itself may not be sold. Backblaze does not endorse this project.
  version: 1.0.0
  contact:
    name: NASdisks
    url: https://www.nasdisks.com/data/
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  x-providerName: nasdisks.com
  x-apisguru-categories:
    - open_data
  x-logo:
    url: https://www.nasdisks.com/icon.svg
servers:
  - url: https://www.nasdisks.com
    description: Production
paths:
  /data/drives.json:
    get:
      operationId: getDrivesJson
      summary: Full drive dataset (JSON)
      description: >-
        Returns the complete NAS-drive dataset as JSON, wrapped with source,
        licensing and attribution metadata. Cached for one hour; CORS open to
        all origins.
      tags:
        - Dataset
      responses:
        '200':
          description: The full dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrivesResponse'
  /data/drives.csv:
    get:
      operationId: getDrivesCsv
      summary: Full drive dataset (CSV)
      description: >-
        Returns the same dataset as a flat CSV download (one row per drive,
        fixed column order). CORS open to all origins.
      tags:
        - Dataset
      responses:
        '200':
          description: CSV download of the dataset.
          content:
            text/csv:
              schema:
                type: string
  /embed/cheapest.json:
    get:
      operationId: getCheapestPerTb
      summary: Cheapest drives by price per TB (region-aware)
      description: >-
        Returns the cheapest in-stock drives ranked by price per terabyte for a
        given Amazon region. Powers the embeddable price widget. Cached per
        region for one hour; CORS open to all origins.
      tags:
        - Pricing
      parameters:
        - name: region
          in: query
          description: >-
            Amazon region code. Invalid values fall back to US.
          required: false
          schema:
            type: string
            default: US
            enum: [US, UK, DE, FR, ES, IT, CA]
        - name: n
          in: query
          description: Number of results to return (1-20).
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 20
      responses:
        '200':
          description: Cheapest-per-TB list for the region.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheapestResponse'
components:
  schemas:
    Drive:
      type: object
      properties:
        model:
          type: string
          example: ST16000NM001G
        brand:
          type: string
          example: Seagate
        line:
          type: string
          example: Exos X16
        capacity_tb:
          type: integer
          example: 16
        rpm:
          type: integer
          nullable: true
          example: 7200
        cache_mb:
          type: integer
          nullable: true
          example: 256
        interface:
          type: string
          nullable: true
          example: SATA 6Gb/s
        form_factor:
          type: string
          nullable: true
          example: 3.5"
        recording_tech:
          type: string
          description: Recording technology, classified per model.
          example: CMR
        acoustic_idle_db:
          type: number
          nullable: true
          description: Idle noise, dB sound power.
          example: 2.8
        acoustic_seek_db:
          type: number
          nullable: true
          description: Seek noise, dB sound power.
          example: 3.2
        is_helium:
          type: boolean
          nullable: true
        drive_class:
          type: string
          nullable: true
          example: Enterprise
        in_production:
          type: boolean
        also_sold_as:
          type: array
          description: Equivalent SKUs (format/firmware/secure-erase/OEM variants) merged into this drive.
          items:
            type: string
          example: [ST16000NM002J]
        afr_pct:
          type: number
          nullable: true
          description: Annualized failure rate (%), recomputed from Backblaze raw data.
          example: 0.42
        reliability_drive_count:
          type: integer
          nullable: true
        reliability_drive_days:
          type: integer
          nullable: true
        reliability_failures:
          type: integer
          nullable: true
        reliability_source:
          type: string
          nullable: true
          example: Backblaze Drive Stats
    DrivesResponse:
      type: object
      properties:
        source:
          type: string
          example: nasdisks.com
        url:
          type: string
          format: uri
        license:
          type: string
          example: CC BY 4.0
        license_url:
          type: string
          format: uri
        license_scope:
          type: string
        attribution:
          type: string
        reliability:
          type: object
          properties:
            fields:
              type: array
              items:
                type: string
            source:
              type: string
            terms:
              type: string
            terms_url:
              type: string
              format: uri
        count:
          type: integer
        drives:
          type: array
          items:
            $ref: '#/components/schemas/Drive'
    CheapestItem:
      type: object
      properties:
        model:
          type: string
        name:
          type: string
        brand:
          type: string
        capacity_tb:
          type: integer
        price:
          type: number
        per_tb:
          type: number
        currency:
          type: string
          example: USD
        symbol:
          type: string
          example: $
        url:
          type: string
          format: uri
    CheapestResponse:
      type: object
      properties:
        source:
          type: string
          example: nasdisks.com
        region:
          type: string
          example: US
        currency:
          type: string
          nullable: true
        home:
          type: string
          format: uri
        items:
          type: array
          items:
            $ref: '#/components/schemas/CheapestItem'