openapi: 3.1.0
info:
  title: MiniProto Public API
  version: '2026-08-21'
  description: >-
    Look up stocked connectors, validate a custom wire-harness specification, obtain a signed price snapshot, and — with
    CustomerOAuth or CustomerApiKey — create a priced draft or engineer-review RFQ. This API does not place orders —
    there is no create_order endpoint; checkout happens on miniproto.com and a human confirms the order. Catalog,
    validation, and price-snapshot routes are anonymous and rate-limited. Quote routes require customer identity.
servers:
  - url: https://www.miniproto.com
    description: Production
components:
  securitySchemes:
    CustomerOAuth:
      type: oauth2
      description: >-
        OAuth 2.1 authorization-code token with PKCE after the host links to an existing MiniProto customer. Writes run
        as that customer. Email on a spec is not identity. Do not send Clerk session cookies or Hermes agent keys. There
        is no create_order endpoint; a live token only creates a draft or RFQ and returns a checkout URL.
      flows:
        authorizationCode:
          authorizationUrl: https://www.miniproto.com/oauth/authorize
          tokenUrl: https://www.miniproto.com/oauth/token
          scopes:
            quotes:read: Read back drafts and RFQs the caller created.
            quotes:write: Create a priced draft or engineer-review RFQ as the linked customer.
    CustomerApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Not live as a directory default. Named B2B keys are issued to an existing customer account after a human
        request. Separate from Hermes agent_api_keys. Send as Authorization: Bearer.
  schemas:
    ConnectorRef:
      description: Public connector reference. Supply exactly one of componentId or mpn — never both, never neither.
      anyOf:
        - description: Identify a connector by MiniProto componentId. Do not include mpn on this object.
          type: object
          properties:
            componentId:
              description: >-
                MiniProto catalog component UUID. Use this when the connector was already resolved via GET
                /api/v1/connectors.
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          required:
            - componentId
          additionalProperties: false
        - description: Identify a connector by manufacturer part number. Do not include componentId on this object.
          type: object
          properties:
            mpn:
              description: >-
                Manufacturer part number as printed on the housing (e.g. DT06-2S). Exact catalog MPNs are unique;
                ambiguous search strings return AMBIGUOUS_MPN.
              type: string
              minLength: 2
              maxLength: 120
          required:
            - mpn
          additionalProperties: false
    Wire:
      description: >-
        One discrete conductor between two connector pins. Field names match the MiniProto CV2 spec used by the quoting
        agent.
      type: object
      properties:
        sourceConnector:
          description: Zero-based index into spec.connectors for the wire from-end. 0 is the first connector in the array.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        sourcePin:
          description: 1-based cavity/pin number on the source connector.
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        targetConnector:
          description: Zero-based index into spec.connectors for the wire to-end. 0 is the first connector in the array.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        targetPin:
          description: 1-based cavity/pin number on the target connector.
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        gauge:
          description: >-
            Conductor gauge. Canonical form is "20 AWG". Also accepted: "20", "20awg", "20 gauge", "20 ga", "#20",
            "AWG20".
          type: string
          minLength: 1
        color:
          description: Insulation color copied verbatim from GET /api/v1/capabilities wireFamilies[].gauges[].colors, e.g. "black".
          type: string
          minLength: 1
        wireFamily:
          description: >-
            Wire family identifier copied verbatim from GET /api/v1/capabilities wireFamilies[].name, e.g. "UL1007",
            "UL1015", "GXL", or "EcoWire".
          type: string
          minLength: 1
        lengthMm:
          description: Finished conductor length in millimetres, measured pin face to pin face.
          type: number
          exclusiveMinimum: 0
      required:
        - sourceConnector
        - sourcePin
        - targetConnector
        - targetPin
        - gauge
        - color
        - wireFamily
        - lengthMm
    HarnessSpec:
      description: 'A complete custom-harness specification: connectors, wires, optional name/notes, and quantity.'
      type: object
      properties:
        projectName:
          description: Optional human-readable name for this harness, 1–200 characters after trim.
          type: string
          minLength: 1
          maxLength: 200
        quantity:
          description: Order quantity for this spec. Defaults to 1. Maximum 100000.
          default: 1
          type: integer
          exclusiveMinimum: 0
          maximum: 100000
        connectors:
          description: Connector endpoints. Minimum 2, maximum 16. Index 0 is the first connector.
          minItems: 2
          maxItems: 16
          type: array
          items:
            description: >-
              One connector endpoint in the harness. Array order is the index used by wires.sourceConnector and
              wires.targetConnector.
            type: object
            properties:
              ref:
                description: 'Connector identity: MiniProto component UUID or manufacturer part number, never both.'
                anyOf:
                  - description: Identify a connector by MiniProto componentId. Do not include mpn on this object.
                    type: object
                    properties:
                      componentId:
                        description: >-
                          MiniProto catalog component UUID. Use this when the connector was already resolved via GET
                          /api/v1/connectors.
                        type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    required:
                      - componentId
                    additionalProperties: false
                  - description: Identify a connector by manufacturer part number. Do not include componentId on this object.
                    type: object
                    properties:
                      mpn:
                        description: >-
                          Manufacturer part number as printed on the housing (e.g. DT06-2S). Exact catalog MPNs are
                          unique; ambiguous search strings return AMBIGUOUS_MPN.
                        type: string
                        minLength: 2
                        maxLength: 120
                    required:
                      - mpn
                    additionalProperties: false
              side:
                description: >-
                  Which side of the harness drawing this connector sits on. Use "left" and "right" as the two ends of a
                  typical cable.
                type: string
                enum:
                  - left
                  - right
              gang:
                description: >-
                  Optional housing gang / cavity-group label when multiple connectors share a shell or should be drawn
                  as a unit.
                type: string
                minLength: 1
                maxLength: 100
            required:
              - ref
              - side
        wires:
          description: Conductors in the harness. Minimum 1, maximum 500.
          minItems: 1
          maxItems: 500
          type: array
          items:
            description: >-
              One discrete conductor between two connector pins. Field names match the MiniProto CV2 spec used by the
              quoting agent.
            type: object
            properties:
              sourceConnector:
                description: Zero-based index into spec.connectors for the wire from-end. 0 is the first connector in the array.
                type: integer
                minimum: 0
                maximum: 9007199254740991
              sourcePin:
                description: 1-based cavity/pin number on the source connector.
                type: integer
                exclusiveMinimum: 0
                maximum: 9007199254740991
              targetConnector:
                description: Zero-based index into spec.connectors for the wire to-end. 0 is the first connector in the array.
                type: integer
                minimum: 0
                maximum: 9007199254740991
              targetPin:
                description: 1-based cavity/pin number on the target connector.
                type: integer
                exclusiveMinimum: 0
                maximum: 9007199254740991
              gauge:
                description: >-
                  Conductor gauge. Canonical form is "20 AWG". Also accepted: "20", "20awg", "20 gauge", "20 ga", "#20",
                  "AWG20".
                type: string
                minLength: 1
              color:
                description: >-
                  Insulation color copied verbatim from GET /api/v1/capabilities wireFamilies[].gauges[].colors, e.g.
                  "black".
                type: string
                minLength: 1
              wireFamily:
                description: >-
                  Wire family identifier copied verbatim from GET /api/v1/capabilities wireFamilies[].name, e.g.
                  "UL1007", "UL1015", "GXL", or "EcoWire".
                type: string
                minLength: 1
              lengthMm:
                description: Finished conductor length in millimetres, measured pin face to pin face.
                type: number
                exclusiveMinimum: 0
            required:
              - sourceConnector
              - sourcePin
              - targetConnector
              - targetPin
              - gauge
              - color
              - wireFamily
              - lengthMm
        designNotes:
          description: Optional free-text notes (max 10000 characters) for manufacturing or quoting context.
          type: string
          maxLength: 10000
      required:
        - connectors
        - wires
    ResolvedConnector:
      description: A connector from the submitted spec after MPN/componentId resolution against the catalog.
      type: object
      properties:
        index:
          description: Zero-based index of this connector in the submitted spec.connectors array.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        componentId:
          description: Resolved MiniProto catalog component UUID.
          type: string
        mpn:
          description: Resolved manufacturer part number.
          type: string
        pinCount:
          description: Number of cavities/pins on the resolved housing.
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - index
        - componentId
        - mpn
        - pinCount
      additionalProperties: false
    ValidationsRequest:
      description: POST /api/v1/validations request body.
      type: object
      properties:
        spec:
          description: Harness specification to validate for manufacturability.
          type: object
          properties:
            projectName:
              description: Optional human-readable name for this harness, 1–200 characters after trim.
              type: string
              minLength: 1
              maxLength: 200
            quantity:
              description: Order quantity for this spec. Defaults to 1. Maximum 100000.
              default: 1
              type: integer
              exclusiveMinimum: 0
              maximum: 100000
            connectors:
              description: Connector endpoints. Minimum 2, maximum 16. Index 0 is the first connector.
              minItems: 2
              maxItems: 16
              type: array
              items:
                description: >-
                  One connector endpoint in the harness. Array order is the index used by wires.sourceConnector and
                  wires.targetConnector.
                type: object
                properties:
                  ref:
                    description: 'Connector identity: MiniProto component UUID or manufacturer part number, never both.'
                    anyOf:
                      - description: Identify a connector by MiniProto componentId. Do not include mpn on this object.
                        type: object
                        properties:
                          componentId:
                            description: >-
                              MiniProto catalog component UUID. Use this when the connector was already resolved via GET
                              /api/v1/connectors.
                            type: string
                            format: uuid
                            pattern: >-
                              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        required:
                          - componentId
                        additionalProperties: false
                      - description: Identify a connector by manufacturer part number. Do not include componentId on this object.
                        type: object
                        properties:
                          mpn:
                            description: >-
                              Manufacturer part number as printed on the housing (e.g. DT06-2S). Exact catalog MPNs are
                              unique; ambiguous search strings return AMBIGUOUS_MPN.
                            type: string
                            minLength: 2
                            maxLength: 120
                        required:
                          - mpn
                        additionalProperties: false
                  side:
                    description: >-
                      Which side of the harness drawing this connector sits on. Use "left" and "right" as the two ends
                      of a typical cable.
                    type: string
                    enum:
                      - left
                      - right
                  gang:
                    description: >-
                      Optional housing gang / cavity-group label when multiple connectors share a shell or should be
                      drawn as a unit.
                    type: string
                    minLength: 1
                    maxLength: 100
                required:
                  - ref
                  - side
            wires:
              description: Conductors in the harness. Minimum 1, maximum 500.
              minItems: 1
              maxItems: 500
              type: array
              items:
                description: >-
                  One discrete conductor between two connector pins. Field names match the MiniProto CV2 spec used by
                  the quoting agent.
                type: object
                properties:
                  sourceConnector:
                    description: >-
                      Zero-based index into spec.connectors for the wire from-end. 0 is the first connector in the
                      array.
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  sourcePin:
                    description: 1-based cavity/pin number on the source connector.
                    type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  targetConnector:
                    description: Zero-based index into spec.connectors for the wire to-end. 0 is the first connector in the array.
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  targetPin:
                    description: 1-based cavity/pin number on the target connector.
                    type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  gauge:
                    description: >-
                      Conductor gauge. Canonical form is "20 AWG". Also accepted: "20", "20awg", "20 gauge", "20 ga",
                      "#20", "AWG20".
                    type: string
                    minLength: 1
                  color:
                    description: >-
                      Insulation color copied verbatim from GET /api/v1/capabilities wireFamilies[].gauges[].colors,
                      e.g. "black".
                    type: string
                    minLength: 1
                  wireFamily:
                    description: >-
                      Wire family identifier copied verbatim from GET /api/v1/capabilities wireFamilies[].name, e.g.
                      "UL1007", "UL1015", "GXL", or "EcoWire".
                    type: string
                    minLength: 1
                  lengthMm:
                    description: Finished conductor length in millimetres, measured pin face to pin face.
                    type: number
                    exclusiveMinimum: 0
                required:
                  - sourceConnector
                  - sourcePin
                  - targetConnector
                  - targetPin
                  - gauge
                  - color
                  - wireFamily
                  - lengthMm
            designNotes:
              description: Optional free-text notes (max 10000 characters) for manufacturing or quoting context.
              type: string
              maxLength: 10000
          required:
            - connectors
            - wires
      required:
        - spec
    ValidationsResponse:
      description: POST /api/v1/validations response body.
      type: object
      properties:
        valid:
          description: True when the spec is manufacturable as submitted; false when errors is non-empty.
          type: boolean
        resolvedConnectors:
          description: Connectors after catalog resolution, in spec.connectors order.
          type: array
          items:
            description: A connector from the submitted spec after MPN/componentId resolution against the catalog.
            type: object
            properties:
              index:
                description: Zero-based index of this connector in the submitted spec.connectors array.
                type: integer
                minimum: 0
                maximum: 9007199254740991
              componentId:
                description: Resolved MiniProto catalog component UUID.
                type: string
              mpn:
                description: Resolved manufacturer part number.
                type: string
              pinCount:
                description: Number of cavities/pins on the resolved housing.
                type: integer
                minimum: 0
                maximum: 9007199254740991
            required:
              - index
              - componentId
              - mpn
              - pinCount
            additionalProperties: false
        errors:
          description: Blocking problems. Empty when valid is true.
          type: array
          items:
            type: string
        warnings:
          description: Non-blocking issues (e.g. unusual length or gauge).
          type: array
          items:
            type: string
      required:
        - valid
        - resolvedConnectors
        - errors
        - warnings
      additionalProperties: false
    PriceSnapshotRequest:
      description: POST /api/v1/price-snapshots request body.
      type: object
      properties:
        spec:
          description: Harness specification to price.
          type: object
          properties:
            projectName:
              description: Optional human-readable name for this harness, 1–200 characters after trim.
              type: string
              minLength: 1
              maxLength: 200
            quantity:
              description: Order quantity for this spec. Defaults to 1. Maximum 100000.
              default: 1
              type: integer
              exclusiveMinimum: 0
              maximum: 100000
            connectors:
              description: Connector endpoints. Minimum 2, maximum 16. Index 0 is the first connector.
              minItems: 2
              maxItems: 16
              type: array
              items:
                description: >-
                  One connector endpoint in the harness. Array order is the index used by wires.sourceConnector and
                  wires.targetConnector.
                type: object
                properties:
                  ref:
                    description: 'Connector identity: MiniProto component UUID or manufacturer part number, never both.'
                    anyOf:
                      - description: Identify a connector by MiniProto componentId. Do not include mpn on this object.
                        type: object
                        properties:
                          componentId:
                            description: >-
                              MiniProto catalog component UUID. Use this when the connector was already resolved via GET
                              /api/v1/connectors.
                            type: string
                            format: uuid
                            pattern: >-
                              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        required:
                          - componentId
                        additionalProperties: false
                      - description: Identify a connector by manufacturer part number. Do not include componentId on this object.
                        type: object
                        properties:
                          mpn:
                            description: >-
                              Manufacturer part number as printed on the housing (e.g. DT06-2S). Exact catalog MPNs are
                              unique; ambiguous search strings return AMBIGUOUS_MPN.
                            type: string
                            minLength: 2
                            maxLength: 120
                        required:
                          - mpn
                        additionalProperties: false
                  side:
                    description: >-
                      Which side of the harness drawing this connector sits on. Use "left" and "right" as the two ends
                      of a typical cable.
                    type: string
                    enum:
                      - left
                      - right
                  gang:
                    description: >-
                      Optional housing gang / cavity-group label when multiple connectors share a shell or should be
                      drawn as a unit.
                    type: string
                    minLength: 1
                    maxLength: 100
                required:
                  - ref
                  - side
            wires:
              description: Conductors in the harness. Minimum 1, maximum 500.
              minItems: 1
              maxItems: 500
              type: array
              items:
                description: >-
                  One discrete conductor between two connector pins. Field names match the MiniProto CV2 spec used by
                  the quoting agent.
                type: object
                properties:
                  sourceConnector:
                    description: >-
                      Zero-based index into spec.connectors for the wire from-end. 0 is the first connector in the
                      array.
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  sourcePin:
                    description: 1-based cavity/pin number on the source connector.
                    type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  targetConnector:
                    description: Zero-based index into spec.connectors for the wire to-end. 0 is the first connector in the array.
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  targetPin:
                    description: 1-based cavity/pin number on the target connector.
                    type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  gauge:
                    description: >-
                      Conductor gauge. Canonical form is "20 AWG". Also accepted: "20", "20awg", "20 gauge", "20 ga",
                      "#20", "AWG20".
                    type: string
                    minLength: 1
                  color:
                    description: >-
                      Insulation color copied verbatim from GET /api/v1/capabilities wireFamilies[].gauges[].colors,
                      e.g. "black".
                    type: string
                    minLength: 1
                  wireFamily:
                    description: >-
                      Wire family identifier copied verbatim from GET /api/v1/capabilities wireFamilies[].name, e.g.
                      "UL1007", "UL1015", "GXL", or "EcoWire".
                    type: string
                    minLength: 1
                  lengthMm:
                    description: Finished conductor length in millimetres, measured pin face to pin face.
                    type: number
                    exclusiveMinimum: 0
                required:
                  - sourceConnector
                  - sourcePin
                  - targetConnector
                  - targetPin
                  - gauge
                  - color
                  - wireFamily
                  - lengthMm
            designNotes:
              description: Optional free-text notes (max 10000 characters) for manufacturing or quoting context.
              type: string
              maxLength: 10000
          required:
            - connectors
            - wires
        quantities:
          description: >-
            Optional extra quantities to include in priceBreaks (1–20 positive integers). The spec.quantity break is
            always included.
          minItems: 1
          maxItems: 20
          type: array
          items:
            type: integer
            exclusiveMinimum: 0
            maximum: 9007199254740991
      required:
        - spec
    PriceSnapshotResponse:
      description: >-
        POST /api/v1/price-snapshots response. Customer-facing prices in USD cents only — never labor, margin, waste, or
        cost internals.
      type: object
      properties:
        priceToken:
          description: >-
            Opaque HMAC token binding this price to the BOM hash. Present this token when converting a snapshot into an
            order; it expires at expiresAt.
          type: string
        priceVersion:
          description: Pricing catalog version that produced this snapshot, e.g. v1-2026-08-20.
          type: string
        expiresAt:
          description: ISO-8601 timestamp after which priceToken is rejected with PRICE_EXPIRED.
          type: string
        currency:
          description: ISO currency code. Always USD.
          type: string
          const: USD
        quantity:
          description: Quantity this snapshot was priced at (spec.quantity).
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        unitPriceCents:
          description: Customer unit price in USD cents for this quantity.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        setupFeeCents:
          description: One-time setup / NRE fee in USD cents for the order, not per unit.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        totalCents:
          description: 'Order total in USD cents: unitPriceCents times quantity plus setupFeeCents.'
          type: integer
          minimum: 0
          maximum: 9007199254740991
        priceBreaks:
          description: Customer price at each requested quantity. Does not include internal cost or margin.
          type: array
          items:
            description: A quantity break with customer unit and total prices in cents.
            type: object
            properties:
              quantity:
                description: Break quantity.
                type: integer
                exclusiveMinimum: 0
                maximum: 9007199254740991
              unitPriceCents:
                description: Customer unit price in USD cents at this quantity.
                type: integer
                minimum: 0
                maximum: 9007199254740991
              totalCents:
                description: Order total in USD cents at this quantity, including setup.
                type: integer
                minimum: 0
                maximum: 9007199254740991
            required:
              - quantity
              - unitPriceCents
              - totalCents
            additionalProperties: false
        bomHash:
          description: SHA-256 hex digest of the canonical BOM; bound into priceToken.
          type: string
        resolvedConnectors:
          description: Connectors after catalog resolution, in spec.connectors order.
          type: array
          items:
            description: A connector from the submitted spec after MPN/componentId resolution against the catalog.
            type: object
            properties:
              index:
                description: Zero-based index of this connector in the submitted spec.connectors array.
                type: integer
                minimum: 0
                maximum: 9007199254740991
              componentId:
                description: Resolved MiniProto catalog component UUID.
                type: string
              mpn:
                description: Resolved manufacturer part number.
                type: string
              pinCount:
                description: Number of cavities/pins on the resolved housing.
                type: integer
                minimum: 0
                maximum: 9007199254740991
            required:
              - index
              - componentId
              - mpn
              - pinCount
            additionalProperties: false
        leadTime:
          description: Selected manufacturing lead-time range, or null if no tier is resolvable.
          anyOf:
            - type: object
              properties:
                tier:
                  description: Lead-time tier id from GET /api/v1/capabilities leadTimes[].tier, e.g. "standard".
                  type: string
                businessDaysMin:
                  description: Inclusive lower bound of manufacturing lead time in business days, or null if unknown.
                  anyOf:
                    - type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    - type: 'null'
                businessDaysMax:
                  description: Inclusive upper bound of manufacturing lead time in business days, or null if unknown.
                  anyOf:
                    - type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    - type: 'null'
              required:
                - tier
                - businessDaysMin
                - businessDaysMax
              additionalProperties: false
            - type: 'null'
      required:
        - priceToken
        - priceVersion
        - expiresAt
        - currency
        - quantity
        - unitPriceCents
        - setupFeeCents
        - totalCents
        - priceBreaks
        - bomHash
        - resolvedConnectors
        - leadTime
      additionalProperties: false
    Connector:
      description: >-
        Public catalog connector. Gender, keying, and lock type are omitted because those columns are not in the
        catalog.
      type: object
      properties:
        componentId:
          description: MiniProto catalog component UUID.
          type: string
        mpn:
          description: Manufacturer part number.
          type: string
        manufacturer:
          description: Manufacturer name, or null if unknown.
          anyOf:
            - type: string
            - type: 'null'
        family:
          description: Connector family display name (e.g. Deutsch DT), or null.
          anyOf:
            - type: string
            - type: 'null'
        familyId:
          description: Connector family UUID, or null.
          anyOf:
            - type: string
            - type: 'null'
        pinCount:
          description: Cavity/pin count, or null if not recorded.
          anyOf:
            - type: integer
              minimum: 0
              maximum: 9007199254740991
            - type: 'null'
        description:
          description: Catalog description, or null.
          anyOf:
            - type: string
            - type: 'null'
        requiresCrimps:
          description: True when this housing requires separate crimp terminals.
          type: boolean
      required:
        - componentId
        - mpn
        - manufacturer
        - family
        - familyId
        - pinCount
        - description
        - requiresCrimps
      additionalProperties: false
    ConnectorListQuery:
      description: GET /api/v1/connectors query parameters.
      type: object
      properties:
        mpn:
          description: Optional exact/prefix manufacturer part number filter (min 2 characters).
          type: string
          minLength: 2
        family:
          description: Optional family name or familyId filter (min 2 characters).
          type: string
          minLength: 2
        pinCount:
          description: Optional cavity/pin count filter. Coerced from the query string.
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        q:
          description: Optional free-text search across MPN and description (min 2 characters).
          type: string
          minLength: 2
        limit:
          description: Page size, 1–100. Defaults to 25. Coerced from the query string.
          default: 25
          type: integer
          minimum: 1
          maximum: 100
      additionalProperties: false
    ConnectorListResponse:
      description: GET /api/v1/connectors response body.
      type: object
      properties:
        connectors:
          description: Matching public catalog connectors.
          type: array
          items:
            description: >-
              Public catalog connector. Gender, keying, and lock type are omitted because those columns are not in the
              catalog.
            type: object
            properties:
              componentId:
                description: MiniProto catalog component UUID.
                type: string
              mpn:
                description: Manufacturer part number.
                type: string
              manufacturer:
                description: Manufacturer name, or null if unknown.
                anyOf:
                  - type: string
                  - type: 'null'
              family:
                description: Connector family display name (e.g. Deutsch DT), or null.
                anyOf:
                  - type: string
                  - type: 'null'
              familyId:
                description: Connector family UUID, or null.
                anyOf:
                  - type: string
                  - type: 'null'
              pinCount:
                description: Cavity/pin count, or null if not recorded.
                anyOf:
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  - type: 'null'
              description:
                description: Catalog description, or null.
                anyOf:
                  - type: string
                  - type: 'null'
              requiresCrimps:
                description: True when this housing requires separate crimp terminals.
                type: boolean
            required:
              - componentId
              - mpn
              - manufacturer
              - family
              - familyId
              - pinCount
              - description
              - requiresCrimps
            additionalProperties: false
        total:
          description: Total matches before the limit is applied.
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - connectors
        - total
      additionalProperties: false
    Capabilities:
      description: 'GET /api/v1/capabilities response: what the public harness API can build and price.'
      type: object
      properties:
        connectorFamilies:
          description: Connector families that can be used in a public harness spec.
          type: array
          items:
            description: One CV2-enabled connector family available to the public API.
            type: object
            properties:
              familyId:
                description: Connector family UUID.
                type: string
              name:
                description: Family display name, e.g. Deutsch DT.
                type: string
              manufacturer:
                description: Manufacturer name, or null.
                anyOf:
                  - type: string
                  - type: 'null'
              category:
                description: Family category (e.g. rectangular, circular), or null.
                anyOf:
                  - type: string
                  - type: 'null'
              awgRange:
                description: Supported AWG range as a string, e.g. "16-22", or null.
                anyOf:
                  - type: string
                  - type: 'null'
            required:
              - familyId
              - name
              - manufacturer
              - category
              - awgRange
            additionalProperties: false
        wireFamilies:
          description: >-
            Wire families accepted in spec.wires[].wireFamily. Call GET /api/v1/capabilities first and copy name, gauge,
            and color verbatim into each wires[] entry.
          type: array
          items:
            description: One orderable wire family with the gauges and colours that may be used in wires[].
            type: object
            properties:
              name:
                description: >-
                  Wire family identifier to send as wires[].wireFamily, e.g. "UL1007". Copy this value verbatim from
                  this list.
                type: string
              description:
                description: Human-readable description of the insulation/rating, or null.
                anyOf:
                  - type: string
                  - type: 'null'
              gauges:
                description: >-
                  Stocked gauges for this family. Each wires[] entry must use a gauge from this list and a color from
                  that gauge's colors array.
                type: array
                items:
                  description: One stocked gauge and the colours available at that gauge in this family.
                  type: object
                  properties:
                    gauge:
                      description: >-
                        Stocked conductor gauge. Canonical form is "20 AWG". Also accepted: "20", "20awg", "20 gauge",
                        "20 ga", "#20", "AWG20".
                      type: string
                    colors:
                      description: >-
                        Stocked insulation colours available at this gauge. Copy one value verbatim as wires[].color,
                        e.g. "black".
                      type: array
                      items:
                        type: string
                  required:
                    - gauge
                    - colors
                  additionalProperties: false
            required:
              - name
              - description
              - gauges
            additionalProperties: false
        leadTimes:
          description: >-
            Published manufacturing lead-time tiers. Each entry is a business-day range. Copy `tier` when a request asks
            for a lead-time selection.
          type: array
          items:
            description: One published lead-time tier.
            type: object
            properties:
              tier:
                description: Lead-time tier id to send back, e.g. "standard".
                type: string
              label:
                description: Customer-facing label for this tier.
                type: string
              businessDaysMin:
                description: Inclusive lower bound of manufacturing lead time in business days, or null if unknown.
                anyOf:
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  - type: 'null'
              businessDaysMax:
                description: Inclusive upper bound of manufacturing lead time in business days, or null if unknown.
                anyOf:
                  - type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  - type: 'null'
              description:
                description: Customer-facing description of this tier, or null.
                anyOf:
                  - type: string
                  - type: 'null'
              isDefault:
                description: True when this is the default tier if the caller does not choose one.
                type: boolean
            required:
              - tier
              - label
              - businessDaysMin
              - businessDaysMax
              - description
              - isDefault
            additionalProperties: false
        limits:
          description: Hard limits enforced by POST /api/v1/validations and /price-snapshots.
          type: object
          properties:
            minConnectorsPerHarness:
              description: Minimum connectors in spec.connectors (currently 2).
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            maxConnectorsPerHarness:
              description: Maximum connectors in spec.connectors (currently 16).
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            maxWiresPerHarness:
              description: Maximum wires in spec.wires (currently 500).
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            minOrderQuantity:
              description: Minimum spec.quantity (currently 1).
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
          required:
            - minConnectorsPerHarness
            - maxConnectorsPerHarness
            - maxWiresPerHarness
            - minOrderQuantity
          additionalProperties: false
        refusals:
          description: >-
            Work this public API will not accept (e.g. overmolding, unterminated flying leads). Do not submit specs that
            require these.
          type: array
          items:
            type: string
        priceVersion:
          description: Current pricing catalog version. Snapshots are bound to this value.
          type: string
      required:
        - connectorFamilies
        - wireFamilies
        - leadTimes
        - limits
        - refusals
        - priceVersion
      additionalProperties: false
    QuoteCreateRequest:
      type: object
      additionalProperties: false
      properties:
        priceId:
          type: string
          description: Signed price snapshot token from POST /api/v1/price-snapshots.
        spec:
          $ref: '#/components/schemas/HarnessSpec'
        notes:
          type: string
          description: RFQ notes when submitting files or a drawing for engineer review.
        projectName:
          type: string
        turnId:
          type: string
    Quote:
      type: object
      required:
        - id
        - quoteNumber
        - url
      properties:
        id:
          type: string
          format: uuid
          description: Quote id.
        quoteNumber:
          type: string
          description: Human quote number.
        checkoutUrl:
          type: string
          format: uri
          description: Checkout URL for a priced draft. Absent on engineer-review RFQs. There is no create_order endpoint.
        url:
          type: string
          format: uri
          description: Human quote review URL on miniproto.com.
    Problem:
      type: object
      description: RFC 9457 problem details. Branch on code, not on title.
      required:
        - type
        - title
        - status
        - code
      properties:
        type:
          type: string
          description: Canonical problem URI, e.g. https://www.miniproto.com/docs/api#error-invalid-input.
        title:
          type: string
          description: Short, human-readable summary.
        status:
          type: integer
          description: HTTP status code.
        code:
          type: string
          enum:
            - INVALID_INPUT
            - NOT_FOUND
            - UNKNOWN_CONNECTOR
            - AMBIGUOUS_MPN
            - DESIGN_INVALID
            - PRICE_EXPIRED
            - PRICE_TOKEN_INVALID
            - IDEMPOTENCY_CONFLICT
            - RATE_LIMITED
            - INTERNAL
          description: Machine-readable error code.
        detail:
          type: string
          description: Optional longer explanation of this occurrence.
        errors:
          description: Optional structured issues (Zod issues, candidate lists, or message strings).
paths:
  /api/v1/capabilities:
    get:
      operationId: getCapabilities
      summary: List public API capabilities
      description: Returns the connector families, wire families, lead-time tiers, and spec limits this API accepts.
      tags:
        - Catalog
      responses:
        '200':
          description: Connector families, wire families, lead times, and spec limits.
          headers: &ref_0
            RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: string
            RateLimit-Reset:
              description: Seconds until the current window resets.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Capabilities'
        '429':
          description: Rate limit exceeded.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected server error.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/v1/connectors:
    get:
      operationId: listConnectors
      summary: List stocked connectors
      description: Filter the public connector catalog by MPN, family, pin count, or free text.
      tags:
        - Catalog
      parameters:
        - name: mpn
          in: query
          required: false
          schema:
            type: string
            minLength: 2
          description: Optional exact/prefix manufacturer part number filter (min 2 characters).
        - name: family
          in: query
          required: false
          schema:
            type: string
            minLength: 2
          description: Optional family name or familyId filter (min 2 characters).
        - name: pinCount
          in: query
          required: false
          schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 9007199254740991
          description: Optional cavity/pin count filter. Coerced from the query string.
        - name: q
          in: query
          required: false
          schema:
            type: string
            minLength: 2
          description: Optional free-text search across MPN and description (min 2 characters).
        - name: limit
          in: query
          required: false
          schema:
            default: 25
            type: integer
            minimum: 1
            maximum: 100
          description: Page size, 1–100. Defaults to 25. Coerced from the query string.
      responses:
        '200':
          description: Matching stocked connectors.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorListResponse'
        '400':
          description: Query failed schema validation.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected server error.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/v1/connectors/{id}:
    get:
      operationId: getConnector
      summary: Get one stocked connector
      description: Fetch one public catalog connector by MiniProto component id.
      tags:
        - Catalog
      parameters:
        - name: id
          in: path
          required: true
          description: MiniProto catalog component UUID.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The stocked connector.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        '404':
          description: No stocked connector with this component id.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: The identifier matched more than one orderable part.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected server error.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/v1/validations:
    post:
      operationId: validateHarness
      summary: Validate a harness spec
      description: Resolve connectors and check that the spec can be built. Does not return a price and does not place an order.
      tags:
        - Harness
      parameters:
        - &ref_1
          name: Idempotency-Key
          in: header
          required: false
          description: >-
            Optional idempotency key. Replaying the same key, route, and body returns the original response with
            Idempotency-Replayed: true.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationsRequest'
      responses:
        '200':
          description: Validation result.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationsResponse'
        '400':
          description: Request body failed schema validation.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: A connector MPN or componentId resolved to nothing.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Ambiguous MPN, or Idempotency-Key reused with a different request body.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: The spec is schema-valid but cannot be built as a harness.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected server error.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/v1/price-snapshots:
    post:
      operationId: createPriceSnapshot
      summary: Create a signed price snapshot
      description: >-
        Validate a harness spec and return a signed price snapshot in USD cents. The snapshot is not an order and does
        not reserve parts or capacity.
      tags:
        - Pricing
      parameters:
        - *ref_1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceSnapshotRequest'
      responses:
        '200':
          description: Signed price snapshot in USD cents.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceSnapshotResponse'
        '400':
          description: Request body failed schema validation.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: A connector MPN or componentId resolved to nothing.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Ambiguous MPN, or Idempotency-Key reused with a different request body.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: The spec is schema-valid but cannot be built as a harness.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected server error, including when price signing is unavailable.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/v1/quotes:
    post:
      operationId: createQuote
      summary: Create a priced draft or engineer-review RFQ
      description: >-
        Authenticated. Send a live priceId plus spec to create a priced draft with checkoutUrl, or notes and PDF/PNG/JPG
        files for engineer review. Does not place an order.
      tags:
        - Quotes
      security:
        - CustomerOAuth:
            - quotes:write
        - CustomerApiKey: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Required idempotency key. Replaying the same key, route, and body returns the original response with
            Idempotency-Replayed: true. Reusing the key with a different body is 409 IDEMPOTENCY_CONFLICT.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteCreateRequest'
          multipart/form-data:
            schema:
              type: object
              properties:
                notes:
                  type: string
                projectName:
                  type: string
                files:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        '200':
          description: Created draft or RFQ.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          description: Invalid body, missing Idempotency-Key, or rejected upload.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Customer authentication required.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: A connector MPN or componentId resolved to nothing.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Expired price token, ambiguous MPN, or Idempotency-Key reused with a different request body.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: The spec is schema-valid but cannot be built as a harness.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected server error.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/v1/quotes/{id}:
    get:
      operationId: getQuote
      summary: Get a draft or RFQ the caller created
      description: Authenticated. Returns the quote if it belongs to the caller. Another customer's quote is 404.
      tags:
        - Quotes
      security:
        - CustomerOAuth:
            - quotes:read
        - CustomerApiKey: []
      parameters:
        - name: id
          in: path
          required: true
          description: Quote UUID.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The caller's draft or RFQ.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          description: Quote id is not a UUID.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Customer authentication required.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Quote not found for this customer.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected server error.
          headers: *ref_0
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
