openapi: 3.1.0
info:
  title: Cofactr Knowledge Graph batch products API
  version: '2026-07-10'
  x-logo:
    url: /static/cofactr_logo.png
  description: Execute multiple product queries in a single request. Each batch member is an operation against the products API expressed as a relative URL; members are fulfilled concurrently and returned in order.
servers:
- url: https://graph.cofactr.com
  description: Production
security:
- ApiKey: []
  ClientId: []
tags:
- name: products
  description: Search, view, and autocomplete electronic component products. Every product is a unique combination of manufacturer (`mfr`) and manufacturer part number (`mpn`), identified by a Cofactr ID (CPID). Product responses are shaped by the requested `schema` and can include specs, documents, compliance data, and market offers.
paths:
  /products/:
    get:
      tags:
      - products
      summary: List products
      description: List products.
      operationId: listProducts
      parameters:
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/External'
      - $ref: '#/components/parameters/ForceRefresh'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 0
          default: 10
          title: Limit
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/Filtering'
      - $ref: '#/components/parameters/Q'
      - $ref: '#/components/parameters/StaleDelta'
      - $ref: '#/components/parameters/SearchStrategy'
      - $ref: '#/components/parameters/Schema'
      responses:
        '200':
          description: Products matching the search query or filters, shaped by the requested `schema` (example shows `product-v1`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
              example:
                data:
                - id: CC2DKKO1LUCF
                  classification: ceramic capacitors
                  description: 0805 0.1 uF 100V ±10% Tolerance X7R SMT Multilayer Ceramic Capacitor
                  hero_image: https://assets.cofactr.com/image/772e5cab-cbf3-337d-99ff-c8ac79448a0c.jpg
                  mfr: Murata
                  mpn: GCM21BR72A104KA37L
                  alt_mpns:
                  - GCM21BR72A104KA37L.
                  - GCM21BR72A104KA37L
                  msl: '1'
                  package: 0805
                  termination_type: SMT
                  lifecycle_status: Production
                  inventory_level: 31089253
                  buyable: 31
                  quotable: 35
                  maybe: 0
                  updated_at: '2026-07-09T22:21:55.650630+00:00'
                  deprecated_ids:
                  - XXLL0JPD4W2X
                  - CC96NA4H7MOT
                  - CCI0BFAAL00D
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded. This may be the monthly product quota or the concurrent-request ceiling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds until the request may be retried. Always present on 429/504.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: string
            X-RateLimit-ResetTime:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Request exceeded the maximum processing time (concurrency-limited clients).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds until the request may be retried. Always present on 429/504.
              schema:
                type: string
  /products/{id}:
    get:
      tags:
      - products
      summary: View product
      description: View product.
      operationId: getProduct
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - $ref: '#/components/parameters/StaleDelta'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/External'
      - $ref: '#/components/parameters/ForceRefresh'
      - $ref: '#/components/parameters/Schema'
      responses:
        '200':
          description: The requested product, shaped by the requested `schema` (example shows `product-offers-v1`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductViewResponse'
              example:
                data:
                  id: CC2DKKO1LUCF
                  classification: ceramic capacitors
                  description: 0805 0.1 uF 100V ±10% Tolerance X7R SMT Multilayer Ceramic Capacitor
                  documents:
                  - label: Datasheet
                    url: https://www.mouser.com/datasheet/2/281/1/GCM21BR72A104KA37_01A-3145807.pdf
                    filename: Untitled
                  - label: Reach Statement
                    url: http://sigma.octopart.com/reach_statement/Murata-company-16.pdf
                    filename: Murata-company-16.pdf
                  hero_image: https://assets.cofactr.com/image/772e5cab-cbf3-337d-99ff-c8ac79448a0c.jpg
                  mfr: Murata
                  mpn: GCM21BR72A104KA37L
                  alt_mpns:
                  - GCM21BR72A104KA37L.
                  - GCM21BR72A104KA37L
                  msl: '1'
                  package: 0805
                  specs:
                  - id: capacitance
                    label: Capacitance
                    display_value: 100 nF
                    quantity:
                      unit: F
                      amount: 1e-07
                  - id: voltagerating_dc_
                    label: Voltage rating (DC)
                    display_value: 100 V
                    quantity:
                      unit: V
                      amount: 100
                  - id: temperaturecoefficient
                    label: Temperature coefficient
                    display_value: X7R
                  product_updated_at: '2026-07-09T22:21:55.650630+00:00'
                  termination_type: SMT
                  deprecated_ids:
                  - XXLL0JPD4W2X
                  - CC96NA4H7MOT
                  - CCI0BFAAL00D
                  min_lead: 3
                  offers:
                  - part: CC2DKKO1LUCF
                    seller:
                      id: 622fb450e4c292d8287b0af5
                      deprecated_ids:
                      - 62d4bcc6412443e55717f293
                      - 62d4bcc6412443e55717f291
                      - 62d4bcc6412443e55717f28f
                      label: Digi-Key
                      aliases:
                      - Digi-Key Kit
                      - Digi-Key Corporation
                      - DIGI-KEY EVALUATION BOARDS
                      - Digikey
                      - Digi-Key Electronics
                      certifications:
                      - AS9120
                      - CFR21
                      lead: 3
                      free_ship:
                        threshold: 250
                        shipping_lead: 2
                      shipping_options:
                      - price: 29.99
                        shipping_lead: 1
                      - price: 13.99
                        shipping_lead: 2
                      - price: 0
                        shipping_lead: 5
                      convenience_return_window: 30
                      scheduled_release_period: 12
                      us_shipping_methods:
                        UPS 1 day: 1
                        UPS 2 day: 2
                        UPS 3 day: 3
                        UPS ground: 5
                      international_shipping_methods:
                        DHL worldwide Express: 3
                        UPS worldwide saver: 4
                      custom_reel_price: 0.0
                    is_authorized: true
                    shipping_lead: 4
                    ships_from_country: US
                    sku: 490-4789-2-ND
                    inventory_level: 652178
                    packaging: Tape & Reel
                    moq: 3000
                    prices:
                    - quantity: 3000
                      price: 0.03828
                      currency: USD
                      converted_currency: USD
                      converted_price: 0.03828
                      conversion_rate: 1.0
                    - quantity: 6000
                      price: 0.0354
                      currency: USD
                      converted_currency: USD
                      converted_price: 0.0354
                      conversion_rate: 1.0
                    - quantity: 9000
                      price: 0.03395
                      currency: USD
                      converted_currency: USD
                      converted_price: 0.03395
                      conversion_rate: 1.0
                    factory_lead_days: 147
                    order_multiple: 1
                    offer_updated_at: '2026-07-11T00:54:11.127659+00:00'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded. This may be the monthly product quota or the concurrent-request ceiling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds until the request may be retried. Always present on 429/504.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: string
            X-RateLimit-ResetTime:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Request exceeded the maximum processing time (concurrency-limited clients).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds until the request may be retried. Always present on 429/504.
              schema:
                type: string
  /products/autocompletions/:
    get:
      tags:
      - products
      summary: List product autocompletions
      description: List product autocompletions.
      operationId: autocompleteProducts
      parameters:
      - $ref: '#/components/parameters/Q'
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 500
            exclusiveMinimum: 0
          - type: 'null'
          description: Maximum number of predictions that may be returned.
          default: 10
          title: Limit
        description: Maximum number of predictions that may be returned.
      responses:
        '200':
          description: Autocomplete predictions for the query, best match first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompletionsResponse'
              example:
                data:
                - id: CC2DKKO1LUCF
                  label: Murata Electronics GCM21BR72A104KA37L
                - id: CCEHW3JXS5CQ
                  label: Murata Electronics GCM21BR71H104KA37L
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded. This may be the monthly product quota or the concurrent-request ceiling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds until the request may be retried. Always present on 429/504.
              schema:
                type: string
            X-RateLimit-Limit:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: string
            X-RateLimit-ResetTime:
              description: Present only when the monthly product quota was exceeded.
              schema:
                type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: Request exceeded the maximum processing time (concurrency-limited clients).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds until the request may be retried. Always present on 429/504.
              schema:
                type: string
components:
  schemas:
    ProductOffersV1Spec:
      title: ProductOffersV1Spec
      description: Product specification for product-offers-v1.
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        display_value:
          type: string
        quantity:
          anyOf:
          - type: 'null'
          - $ref: '#/components/schemas/ProductOffersV1Quantity'
          default: null
      required:
      - id
      - label
      - display_value
    ProductViewResponse:
      type: object
      description: 'The shape of `data` is selected by the required `schema` query parameter: `product-v0` → ProductV0, `product-v1` → ProductV1, `product-offers-v0` → ProductOffersV0, `product-offers-v1` → ProductOffersV1.'
      required:
      - data
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/ProductV0'
          - $ref: '#/components/schemas/ProductV1'
          - $ref: '#/components/schemas/ProductOffersV0'
          - $ref: '#/components/schemas/ProductOffersV1'
    ProductSpec:
      title: ProductSpec
      description: Class name is part of the public OpenAPI contract. Do not rename casually.
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        value:
          type: string
      required:
      - id
      - label
      - value
    ProductOffersV1Seller:
      title: ProductOffersV1Seller
      description: Seller fields exposed by product-offers-v1.
      type: object
      properties:
        id:
          type: string
        deprecated_ids:
          type: array
          items:
            type: string
          default: []
        label:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        aliases:
          type: array
          items:
            type: string
          default: []
        certifications:
          type: array
          items:
            type: string
          default: []
        lead:
          type: integer
        free_ship:
          $ref: '#/components/schemas/FreeShipTerms'
        shipping_options:
          type: array
          items:
            type: object
        best_case_lead:
          anyOf:
          - type: integer
          - type: 'null'
        convenience_return_window:
          anyOf:
          - type: integer
          - type: 'null'
        scheduled_release_period:
          anyOf:
          - type: integer
          - type: 'null'
        us_shipping_methods:
          type: object
          additionalProperties:
            type: integer
        international_shipping_methods:
          type: object
          additionalProperties:
            type: integer
        custom_reel_price:
          anyOf:
          - type: number
          - type: 'null'
      required:
      - id
      - lead
      - shipping_options
      - best_case_lead
      - convenience_return_window
      - scheduled_release_period
      - us_shipping_methods
      - international_shipping_methods
      - custom_reel_price
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    OffersV0:
      title: OffersV0
      description: Offers v0 schema.
      type: object
      properties:
        part:
          type: string
        seller:
          $ref: '#/components/schemas/Seller'
        is_authorized:
          type: boolean
          default: false
        status:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        shipping_lead:
          type: integer
        ships_from_country:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        sku:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        inventory_level:
          type: integer
          default: 0
        packaging:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        moq:
          type: integer
          default: 1
        prices:
          type: array
          items:
            $ref: '#/components/schemas/PricePoint'
          default: []
        updated_at:
          type: string
        factory_lead_days:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        on_order_quantity:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        factory_pack_quantity:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        order_multiple:
          type: integer
          default: 1
        multipack_quantity:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        is_foreign:
          type: boolean
          default: false
      required:
      - part
      - seller
      - shipping_lead
      - updated_at
    ProductOffersV1:
      title: ProductOffersV1
      description: Product details with offers for new public API integrations.
      type: object
      properties:
        id:
          type: string
        classification:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        description:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        documents:
          type: array
          items:
            $ref: '#/components/schemas/ProductDocument'
          default: []
        hero_image:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        mfr:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        mpn:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        alt_mpns:
          type: array
          items:
            type: string
          default: []
        msl:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        package:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        specs:
          type: array
          items:
            $ref: '#/components/schemas/ProductOffersV1Spec'
          default: []
        terminations:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        product_updated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        termination_type:
          type: string
          default: other
        deprecated_ids:
          type: array
          items:
            type: string
          default: []
        min_lead:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        offers:
          type: array
          items:
            $ref: '#/components/schemas/ProductOffersV1Offer'
          default: []
      required:
      - id
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Error:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
          description: Human-readable explanation of the error.
    ProductOffersV1Quantity:
      title: ProductOffersV1Quantity
      description: Structured quantity for product-offers-v1 specs.
      type: object
      properties:
        unit:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        amount:
          anyOf:
          - type: number
          - type: 'null'
          default: null
        lower_bound:
          anyOf:
          - type: number
          - type: 'null'
          default: null
        upper_bound:
          anyOf:
          - type: number
          - type: 'null'
          default: null
      required: []
    ProductOffersV1Offer:
      title: ProductOffersV1Offer
      description: Supplier offer for product-offers-v1.
      type: object
      properties:
        part:
          type: string
        seller:
          $ref: '#/components/schemas/ProductOffersV1Seller'
        is_authorized:
          type: boolean
          default: false
        shipping_lead:
          type: integer
        ships_from_country:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        sku:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        inventory_level:
          type: integer
          default: 0
        packaging:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        moq:
          type: integer
          default: 1
        prices:
          type: array
          items:
            $ref: '#/components/schemas/PricePoint'
          default: []
        offer_updated_at:
          type: string
        factory_lead_days:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        factory_pack_quantity:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        order_multiple:
          type: integer
          default: 1
      required:
      - part
      - seller
      - shipping_lead
      - offer_updated_at
    ProductDocument:
      title: ProductDocument
      description: Class name is part of the public OpenAPI contract. Do not rename casually.
      type: object
      properties:
        label:
          type: string
        url:
          type: string
        filename:
          type: string
      required:
      - label
      - url
      - filename
    PricePoint:
      title: PricePoint
      description: "Price in a specific currency + quantity.\n    Based on https://octopart.com/api/v4/reference#pricepoint\n\n    Class name is part of the public OpenAPI contract. Do not rename casually."
      type: object
      properties:
        quantity:
          anyOf:
          - type: integer
          - type: 'null'
        price:
          anyOf:
          - type: number
          - type: 'null'
        currency:
          anyOf:
          - type: string
          - type: 'null'
        converted_currency:
          anyOf:
          - type: string
          - type: 'null'
        converted_price:
          anyOf:
          - type: number
          - type: 'null'
        conversion_rate:
          anyOf:
          - type: number
          - type: 'null'
      required:
      - quantity
      - price
      - currency
      - converted_currency
      - converted_price
      - conversion_rate
    SearchStrategy:
      type: string
      enum:
      - default
      - mpn_exact_mfr
      - mpn_exact
      - mpn_exact_multi
      - mpn_sku_mfr
      title: SearchStrategy
      description: Search strategy.
    ProductOffersV0:
      title: ProductOffersV0
      type: object
      properties:
        id:
          type: string
        classification:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        description:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        documents:
          type: array
          items:
            $ref: '#/components/schemas/ProductDocument'
          default: []
        hero_image:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        mfr:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        mpn:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        alt_mpns:
          type: array
          items:
            type: string
          default: []
        msl:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        package:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        specs:
          type: array
          items:
            $ref: '#/components/schemas/ProductSpec'
          default: []
        terminations:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        inventory_level:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        buyable:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        quotable:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        maybe:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        termination_type:
          type: string
          default: other
        buyable_reference_prices:
          type: array
          items:
            $ref: '#/components/schemas/PricePoint'
          default: []
        reference_prices:
          type: array
          items:
            $ref: '#/components/schemas/PricePoint'
          default: []
        deprecated_ids:
          type: array
          items:
            type: string
          default: []
        min_lead:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        offers:
          type: array
          items:
            $ref: '#/components/schemas/OffersV0'
          default: []
      required:
      - id
    AutocompletionsResponse:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Autocompletion'
    ProductV1:
      title: ProductV1
      description: Basic product information model for external API responses.
      type: object
      properties:
        id:
          type: string
        classification:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        description:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        hero_image:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        mfr:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        mpn:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        alt_mpns:
          type: array
          items:
            type: string
          default: []
        msl:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        package:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        terminations:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        termination_type:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        lifecycle_status:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        inventory_level:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        buyable:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        quotable:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        maybe:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        deprecated_ids:
          type: array
          items:
            type: string
          default: []
      required:
      - id
    FreeShipTerms:
      title: FreeShipTerms
      description: Class name is part of the public OpenAPI contract. Do not rename casually.
      type: object
      properties:
        threshold:
          anyOf:
          - type: number
          - type: 'null'
          default: null
        shipping_lead:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
      required: []
    Seller:
      title: Seller
      description: Class name is part of the public OpenAPI contract. Do not rename casually.
      type: object
      properties:
        id:
          type: string
        deprecated_ids:
          type: array
          items:
            type: string
          default: []
        label:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        aliases:
          type: array
          items:
            type: string
          default: []
        additional_fee:
          anyOf:
          - type: number
          - type: 'null'
          default: null
        additional_markup:
          anyOf:
          - type: number
          - type: 'null'
          default: null
        authenticity_score:
          type: number
        availability_score:
          type: number
        certifications:
          type: array
          items:
            type: string
          default: []
        is_buyable:
          type: boolean
        lead:
          type: integer
        free_ship:
          $ref: '#/components/schemas/FreeShipTerms'
        shipping_options:
          type: array
          items:
            type: object
        best_case_lead:
          anyOf:
          - type: integer
          - type: 'null'
        overlap:
          type: boolean
        convenience_return_window:
          anyOf:
          - type: integer
          - type: 'null'
        scheduled_release_period:
          anyOf:
          - type: integer
          - type: 'null'
        is_api_ordering_supported:
          type: boolean
        is_api_order_status_supported:
          type: boolean
        us_shipping_methods:
          type: object
          additionalProperties:
            type: integer
        international_shipping_methods:
          type: object
          additionalProperties:
            type: integer
        custom_reel_price:
          anyOf:
          - type: number
          - type: 'null'
      required:
      - id
      - authenticity_score
      - availability_score
      - is_buyable
      - lead
      - shipping_options
      - best_case_lead
      - overlap
      - convenience_return_window
      - scheduled_release_period
      - is_api_ordering_supported
      - is_api_order_status_supported
      - us_shipping_methods
      - international_shipping_methods
      - custom_reel_price
    Autocompletion:
      type: object
      required:
      - id
      - label
      properties:
        id:
          type: string
          description: Cofactr product ID (CPID).
        label:
          type: string
          description: 'Display label: manufacturer + MPN.'
    ProductV0:
      title: ProductV0
      description: Basic product information model for external API responses.
      type: object
      properties:
        id:
          type: string
        classification:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        description:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        hero_image:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        mfr:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        mpn:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        alt_mpns:
          type: array
          items:
            type: string
          default: []
        msl:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        package:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        terminations:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        termination_type:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        lifecycle_status:
          anyOf:
          - type: string
          - type: 'null'
          default: null
        inventory_level:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        buyable:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        quotable:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        maybe:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
      required:
      - id
    ProductListResponse:
      type: object
      description: 'The shape of `data` is selected by the required `schema` query parameter: `product-v0` → ProductV0, `product-v1` → ProductV1, `product-offers-v0` → ProductOffersV0, `product-offers-v1` → ProductOffersV1.'
      required:
      - data
      properties:
        data:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/ProductV0'
            - $ref: '#/components/schemas/ProductV1'
            - $ref: '#/components/schemas/ProductOffersV0'
            - $ref: '#/components/schemas/ProductOffersV1'
  parameters:
    SearchStrategy:
      name: search_strategy
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/SearchStrategy'
        description: 'Search strategy for interpreting `q`:

          - `default`: general search across MPN, alt MPNs, SKU, manufacturer, classification, and description, with partial/autocomplete matching; results sorted by inventory descending.

          - `mpn_exact`: `q` must exactly match one of the product''s MPNs (including alternates).

          - `mpn_exact_multi`: `q` is querystring-encoded (`mpn=A&mpn=B`, repeatable); matches products whose MPN exactly matches any of the given values.

          - `mpn_exact_mfr`: `q` is querystring-encoded (`mpn=...&mfr=...`, repeatable); exact MPN match, optionally constrained to the given manufacturer(s).

          - `mpn_sku_mfr`: tailored for BOM matching where `q` is an MPN optionally followed by a manufacturer; scores MPN/alt-MPN/SKU/manufacturer matches and sorts by inventory descending.

          '
        default: default
      description: 'Search strategy for interpreting `q`:

        - `default`: general search across MPN, alt MPNs, SKU, manufacturer, classification, and description, with partial/autocomplete matching; results sorted by inventory descending.

        - `mpn_exact`: `q` must exactly match one of the product''s MPNs (including alternates).

        - `mpn_exact_multi`: `q` is querystring-encoded (`mpn=A&mpn=B`, repeatable); matches products whose MPN exactly matches any of the given values.

        - `mpn_exact_mfr`: `q` is querystring-encoded (`mpn=...&mfr=...`, repeatable); exact MPN match, optionally constrained to the given manufacturer(s).

        - `mpn_sku_mfr`: tailored for BOM matching where `q` is an MPN optionally followed by a manufacturer; scores MPN/alt-MPN/SKU/manufacturer matches and sorts by inventory descending.

        '
    Fields:
      name: fields
      in: query
      required: false
      schema:
        anyOf:
        - type: string
        - type: 'null'
        description: Comma-separated list of fields to return.
        title: Fields
      description: Comma-separated list of fields to return.
    PageToken:
      name: page_token
      in: query
      required: false
      schema:
        anyOf:
        - type: string
        - type: 'null'
        description: Base64 encoded page token used for pagination.
        title: Page Token
      description: Base64 encoded page token used for pagination.
    StaleDelta:
      name: stale_delta
      in: query
      required: false
      schema:
        type:
        - string
        - 'null'
        description: 'How long until offer data is considered stale: a duration string (e.g. "15m", "2h", "1d") or "inf" to never treat cached offer data as stale. Server default: 3 days. Only consulted when a refresh is performed (`external=true` or `force_refresh=true`).'
      description: 'How long until offer data is considered stale: a duration string (e.g. "15m", "2h", "1d") or "inf" to never treat cached offer data as stale. Server default: 3 days. Only consulted when a refresh is performed (`external=true` or `force_refresh=true`).'
    Filtering:
      name: filtering
      in: query
      required: false
      schema:
        anyOf:
        - type: string
        - type: 'null'
        description: Filters to apply for the search.
        title: Filtering
      description: Filters to apply for the search.
      example: '[{"field":"id","operator":"IN","value":["CC2DKKO1LUCF"]}]'
    Q:
      name: q
      in: query
      required: false
      schema:
        anyOf:
        - type: string
        - type: 'null'
        description: Search query. Its interpretation depends on `search_strategy`; that parameter documents the syntax for each strategy.
        title: Q
      description: Search query. Its interpretation depends on `search_strategy`; that parameter documents the syntax for each strategy.
      example: GCM21BR72A104KA37L
    External:
      name: external
      in: query
      required: false
      schema:
        anyOf:
        - type: boolean
        - type: 'null'
        description: Whether to fetch external data.
        default: false
        title: External
      description: Whether to fetch external data.
      example: true
    Schema:
      name: schema
      in: query
      required: true
      schema:
        type: string
        description: 'Response schema for the returned product(s). Public values: `product-v0`, `product-v1`, `product-offers-v0`, `product-offers-v1`. Prefer `product-offers-v1` for new integrations that need offers and structured spec quantities. Schemas are versioned, and older versions remain available. Additional bespoke schemas exist for specific customers by arrangement with the Cofactr team.'
        examples:
        - product-v0
        - product-v1
        - product-offers-v0
        - product-offers-v1
        title: Schema
      description: 'Response schema for the returned product(s). Public values: `product-v0`, `product-v1`, `product-offers-v0`, `product-offers-v1`. Prefer `product-offers-v1` for new integrations that need offers and structured spec quantities. Schemas are versioned, and older versions remain available. Additional bespoke schemas exist for specific customers by arrangement with the Cofactr team.'
      example: product-v1
    ForceRefresh:
      name: force_refresh
      in: query
      required: false
      schema:
        anyOf:
        - type: boolean
        - type: 'null'
        description: Whether to force re-ingestion from external sources. Overrides `external`.
        default: false
        title: Force Refresh
      description: Whether to force re-ingestion from external sources. Overrides `external`.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Issued with your client ID as one Cofactr credential set. Never expose your API key in front-end code or public Git repositories. The Cofactr API is for server-side use only. Public disclosure of a key results in immediate revocation without prior warning.
      x-display-name: API key
      x-auth-set: CofactrCredentials
      x-auth-set-display-name: Cofactr API credentials
    ClientId:
      type: apiKey
      in: header
      name: X-CLIENT-ID
      description: Issued with your API key as one Cofactr credential set.
      x-display-name: Client ID
      x-auth-set: CofactrCredentials
      x-auth-set-display-name: Cofactr API credentials