> ## Documentation Index
> Fetch the complete documentation index at: https://api.nektir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a family and its current product members

> Returns every current member with its own vintage, age statement, package, price, DABS lifecycle status, availability summary, and last successful inventory retrieval time.



## OpenAPI

````yaml /openapi/v1.yaml get /product-families/{family_id}
openapi: 3.1.0
info:
  title: Independent Utah DABS API
  version: 1.0.0
  summary: Database-backed product, store, and reported-inventory reads
  description: >
    Version 1 pilot contract. All requests read a locally published database
    revision;

    no public request waits for or triggers Utah DABS. Reported quantities are

    observations, not purchase guarantees. This service is independent and is
    not

    affiliated with or endorsed by Utah DABS. The current local seed contains

    historical inventory fixtures; clients must inspect response warnings and

    coverage metadata.
servers:
  - url: http://127.0.0.1:5185/v1
    description: Local development only; set MINTLIFY_API_BASE_URL before publishing
security: []
tags:
  - name: Products
  - name: Brands
  - name: Product families
  - name: Changes
  - name: Exports
  - name: Stores
  - name: Availability
  - name: Metadata
paths:
  /product-families/{family_id}:
    get:
      tags:
        - Product families
      summary: Get a family and its current product members
      description: >-
        Returns every current member with its own vintage, age statement,
        package, price, DABS lifecycle status, availability summary, and last
        successful inventory retrieval time.
      operationId: getProductFamily
      parameters:
        - $ref: '#/components/parameters/FamilyIdPath'
        - $ref: '#/components/parameters/IfNoneMatch'
        - $ref: '#/components/parameters/IfModifiedSince'
      responses:
        '200':
          description: Product family detail from one immutable publication revision.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/DetailCacheControl'
            X-Publication-Revision:
              $ref: '#/components/headers/PublicationRevision'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductFamilyResponse'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    FamilyIdPath:
      name: family_id
      in: path
      required: true
      description: Stable API-owned product-family UUID.
      schema:
        type: string
        format: uuid
    IfNoneMatch:
      name: If-None-Match
      in: header
      description: Strong entity tag from an earlier response.
      schema:
        type: string
    IfModifiedSince:
      name: If-Modified-Since
      in: header
      description: HTTP-date fallback validator. ETag takes precedence.
      schema:
        type: string
  headers:
    ETag:
      description: >-
        Strong validator for the response representation. A new publication may
        retain the validator when this response is unchanged.
      schema:
        type: string
      example: '"v1-018f2fd0-a3d4-7d20-9c11-9482722f6b26-a91c"'
    LastModified:
      description: >-
        Newest relevant publication time in HTTP-date format; not an upstream
        update time.
      schema:
        type: string
      example: Tue, 15 Sep 2026 16:31:00 GMT
    DetailCacheControl:
      schema:
        type: string
      example: public, max-age=60, stale-while-revalidate=300
    PublicationRevision:
      description: Immutable API publication revision used for this representation.
      schema:
        type: string
        format: uuid
    RetryAfter:
      description: Seconds until retry or an HTTP-date.
      schema:
        type: string
    RequestId:
      description: >-
        Server-generated identifier for correlating a response with private
        operational logs.
      schema:
        type: string
        format: uuid
  schemas:
    ProductFamilyResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: '#/components/schemas/ProductFamily'
        meta:
          $ref: '#/components/schemas/ResourceMeta'
    ProductFamily:
      type: object
      additionalProperties: false
      required:
        - id
        - slug
        - name
        - brand
        - brand_id
        - member_count
        - category_ids
        - price_range
        - inventory_retrieved_at
        - observed_history
        - members
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        brand:
          type:
            - string
            - 'null'
        brand_id:
          type:
            - string
            - 'null'
          format: uuid
        member_count:
          type: integer
          minimum: 1
        category_ids:
          type: array
          uniqueItems: true
          items:
            type: string
            pattern: ^cat_[a-z0-9_]+$
        price_range:
          oneOf:
            - $ref: '#/components/schemas/ProductFamilyPriceRange'
            - type: 'null'
        inventory_retrieved_at:
          type:
            - string
            - 'null'
          format: date-time
        observed_history:
          oneOf:
            - $ref: '#/components/schemas/ProductFamilyObservedHistory'
            - type: 'null'
        members:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ProductFamilyMember'
    ResourceMeta:
      type: object
      additionalProperties: false
      required:
        - warnings
      properties:
        freshness:
          $ref: '#/components/schemas/ProductResourceFreshness'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
    Problem:
      type: object
      additionalProperties: false
      required:
        - type
        - title
        - status
        - detail
        - instance
        - code
        - request_id
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
        code:
          type: string
        request_id:
          type: string
          format: uuid
        invalid_params:
          type: array
          items:
            $ref: '#/components/schemas/InvalidParameter'
    ProductFamilyPriceRange:
      type: object
      additionalProperties: false
      required:
        - currency
        - minimum_amount_minor
        - maximum_amount_minor
      properties:
        currency:
          type: string
          const: USD
        minimum_amount_minor:
          type:
            - integer
            - 'null'
          minimum: 0
        maximum_amount_minor:
          type:
            - integer
            - 'null'
          minimum: 0
    ProductFamilyObservedHistory:
      type: object
      additionalProperties: false
      required:
        - tracking_started_at
        - earliest_observed_at
        - latest_observed_at
        - retained_change_count
        - recent_change_count_30d
        - last_price_change_at
        - last_inventory_change_at
        - observed_price
        - member_count
        - members_reporting_stock
        - positive_store_product_pairs
        - last_reported_positive_at
        - retention_days
        - semantics
      properties:
        tracking_started_at:
          type: string
          format: date-time
        earliest_observed_at:
          type:
            - string
            - 'null'
          format: date-time
        latest_observed_at:
          type:
            - string
            - 'null'
          format: date-time
        retained_change_count:
          type: integer
          minimum: 0
        recent_change_count_30d:
          type: integer
          minimum: 0
        last_price_change_at:
          type:
            - string
            - 'null'
          format: date-time
        last_inventory_change_at:
          type:
            - string
            - 'null'
          format: date-time
        observed_price:
          $ref: '#/components/schemas/ProductFamilyPriceRange'
        member_count:
          type: integer
          minimum: 1
        members_reporting_stock:
          type: integer
          minimum: 0
        positive_store_product_pairs:
          type: integer
          minimum: 0
        last_reported_positive_at:
          type:
            - string
            - 'null'
          format: date-time
        retention_days:
          type: integer
          minimum: 30
        semantics:
          type: string
          const: >-
            current_family_members_published_observations_not_inferred_sales_or_continuous_history
    ProductFamilyMember:
      type: object
      additionalProperties: false
      required:
        - id
        - source_ids
        - name
        - brand
        - relationship_type
        - vintage_year
        - age_statement
        - package_size
        - price
        - status
        - inventory_retrieved_at
        - availability_summary
      properties:
        id:
          type: string
          format: uuid
        source_ids:
          $ref: '#/components/schemas/SourceProductIds'
        name:
          type: string
        brand:
          type:
            - string
            - 'null'
        relationship_type:
          type: string
          enum:
            - expression
            - package_variant
            - successor
            - other
        vintage_year:
          type:
            - integer
            - 'null'
          minimum: 1900
          maximum: 2099
        age_statement:
          type:
            - string
            - 'null'
        package_size:
          $ref: '#/components/schemas/PackageSize'
        price:
          oneOf:
            - $ref: '#/components/schemas/MoneyObservation'
            - type: 'null'
        status:
          $ref: '#/components/schemas/ProductStatus'
        inventory_retrieved_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Last successful Nektir retrieval among this member's current
            published store observations.
        availability_summary:
          $ref: '#/components/schemas/AvailabilitySummary'
    ProductResourceFreshness:
      type: object
      additionalProperties: false
      required:
        - catalog
        - inventory
      properties:
        catalog:
          $ref: '#/components/schemas/NullableObservationTimes'
        inventory:
          type: object
          additionalProperties: false
          required:
            - source_updated_at
            - retrieved_at_min
            - retrieved_at_max
            - published_at
            - upstream_age_known
          properties:
            source_updated_at:
              type:
                - string
                - 'null'
              format: date-time
            retrieved_at_min:
              type:
                - string
                - 'null'
              format: date-time
            retrieved_at_max:
              type:
                - string
                - 'null'
              format: date-time
            published_at:
              type:
                - string
                - 'null'
              format: date-time
            upstream_age_known:
              type: boolean
              const: false
    Warning:
      type: object
      additionalProperties: false
      description: >-
        Machine-readable data qualification. Current codes include FIXTURE_DATA,
        INVENTORY_COVERAGE_PARTIAL, SOURCE_REFRESH_DELAYED,
        UPSTREAM_PRODUCT_UNAVAILABLE, SOURCE_SCHEMA_QUARANTINED, and
        CATALOG_BATCH_OLD.
      required:
        - code
      properties:
        code:
          type: string
          examples:
            - INVENTORY_COVERAGE_PARTIAL
    InvalidParameter:
      type: object
      additionalProperties: false
      required:
        - name
        - reason
      properties:
        name:
          type: string
        reason:
          type: string
    SourceProductIds:
      type: object
      additionalProperties: false
      required:
        - utah_dabs_sku
      properties:
        utah_dabs_sku:
          $ref: '#/components/schemas/DabsSku'
    PackageSize:
      type: object
      additionalProperties: false
      required:
        - milliliters
        - display
        - normalization_state
      properties:
        milliliters:
          type:
            - integer
            - 'null'
          minimum: 1
        display:
          type: string
        normalization_state:
          type: string
          enum:
            - normalized
            - unconfirmed
            - missing
    MoneyObservation:
      type: object
      additionalProperties: false
      required:
        - amount_minor
        - currency
        - display
        - source
        - times
      properties:
        amount_minor:
          type: integer
          format: int64
          minimum: 0
        currency:
          type: string
          const: USD
        display:
          type: string
          examples:
            - $19.99
        source:
          type: string
          enum:
            - utah_dabs_workbook
            - utah_dabs_locator
        times:
          $ref: '#/components/schemas/ObservationTimes'
    ProductStatus:
      type: object
      additionalProperties: false
      required:
        - code
        - label
        - lifecycle
        - source_raw
      properties:
        code:
          type: string
          examples:
            - '1'
        label:
          type: string
          examples:
            - General distribution
        lifecycle:
          type: string
          enum:
            - active
            - discontinued
            - restricted
            - unavailable
            - unknown
        source_raw:
          type: string
    AvailabilitySummary:
      type: object
      additionalProperties: false
      required:
        - scope_store_count
        - reported_positive_store_count
        - eligible_positive_store_count
        - reported_zero_store_count
        - row_absent_store_count
        - unchecked_store_count
        - retrieved_at_min
        - retrieved_at_max
        - retrieval_policy_id
        - meets_retrieval_policy
        - upstream_age_known
        - last_refresh_attempt
      properties:
        scope_store_count:
          type: integer
          minimum: 0
        reported_positive_store_count:
          type: integer
          minimum: 0
        eligible_positive_store_count:
          type: integer
          minimum: 0
        reported_zero_store_count:
          type: integer
          minimum: 0
        row_absent_store_count:
          type: integer
          minimum: 0
        unchecked_store_count:
          type: integer
          minimum: 0
        retrieved_at_min:
          type:
            - string
            - 'null'
          format: date-time
        retrieved_at_max:
          type:
            - string
            - 'null'
          format: date-time
        retrieval_policy_id:
          type: string
        meets_retrieval_policy:
          type: boolean
        upstream_age_known:
          type: boolean
          const: false
        last_refresh_attempt:
          $ref: '#/components/schemas/RefreshAttemptSummary'
    NullableObservationTimes:
      type: object
      additionalProperties: false
      required:
        - source_updated_at
        - retrieved_at
        - published_at
      properties:
        source_updated_at:
          type:
            - string
            - 'null'
          format: date-time
        retrieved_at:
          type:
            - string
            - 'null'
          format: date-time
        published_at:
          type:
            - string
            - 'null'
          format: date-time
    DabsSku:
      type: string
      pattern: ^[0-9]{6}$
      examples:
        - '347210'
        - '004190'
    ObservationTimes:
      type: object
      additionalProperties: false
      required:
        - source_updated_at
        - retrieved_at
        - published_at
      properties:
        source_updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Null when the source supplies no update timestamp.
        retrieved_at:
          type: string
          format: date-time
        published_at:
          type: string
          format: date-time
    RefreshAttemptSummary:
      type: object
      additionalProperties: false
      required:
        - attempted_at
        - status
      properties:
        attempted_at:
          type:
            - string
            - 'null'
          format: date-time
        status:
          type: string
          enum:
            - succeeded
            - failed
            - skipped
            - rate_limited
            - schema_rejected
            - never_attempted
  responses:
    NotModified:
      description: Representation has not changed for the supplied validator.
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Cache-Control:
          description: Cache policy for the validated representation.
          schema:
            type: string
        X-Publication-Revision:
          $ref: '#/components/headers/PublicationRevision'
    BadRequest:
      description: Invalid parameters, incompatible scope, or cursor/query mismatch.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: Published resource or source mapping not found.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    RateLimited:
      description: Public read-rate limit exceeded.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalError:
      description: >-
        An unexpected server failure. Details are withheld; report the response
        request identifier.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unavailable:
      description: No safe published database revision is currently readable.
      headers:
        Cache-Control:
          schema:
            type: string
          example: no-store
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

````