BuyingMesh Products API

openapi: 3.2.0
info:
  title: BuyingMesh Procurement Products API
  version: 0.5.4
  description: Structured supplier and product API for buying agents. Product discovery exposes reviewed merchant listings with explicit price, lead-time and inventory evidence; the current public catalog contains 86 approved production SKUs from one reviewed supplier and reports confirmed inventory in the current snapshot. Read each SKU inventoryStatus and dataFreshness before quoting. x402 payments and real order creation are disabled until production settlement and fulfillment are ready. All REST responses use the JSON envelope {status, data, error}; MCP remains JSON-RPC. Merchant applications are open now.
servers:
- url: https://buyingmesh.com
tags:
- name: Products
paths:
  /v1/products:
    get:
      operationId: searchProducts
      summary: Search structured products
      parameters:
      - name: q
        in: query
        schema:
          type: string
      - name: sku
        in: query
        description: Exact SKU match
        schema:
          type: string
      - name: gtin
        in: query
        description: Exact GTIN match
        schema:
          type: string
      - name: category
        in: query
        schema:
          type: string
          example: stainless-fasteners
      - name: supplierId
        in: query
        schema:
          type: string
      - name: supplierSlug
        in: query
        schema:
          type: string
      - name: material
        in: query
        description: Case-insensitive partial match
        schema:
          type: string
      - name: size
        in: query
        description: Case-insensitive partial match
        schema:
          type: string
      - name: minMoq
        in: query
        schema:
          type: integer
          minimum: 1
      - name: maxMoq
        in: query
        schema:
          type: integer
          minimum: 1
      - name: minPrice
        in: query
        schema:
          type: number
          minimum: 0
      - name: maxPrice
        in: query
        schema:
          type: number
          format: double
      - name: currency
        in: query
        schema:
          type: string
          example: USD
      - name: minInventory
        in: query
        schema:
          type: integer
          minimum: 0
      - name: inventoryStatus
        in: query
        schema:
          type: string
          enum:
          - confirmed
          - unknown
      - name: maxLeadTimeDays
        in: query
        schema:
          type: integer
          minimum: 0
      - name: qualificationStatus
        in: query
        schema:
          type: string
      - name: verifiedOnly
        in: query
        schema:
          type: boolean
      - name: freshnessWithinMinutes
        in: query
        schema:
          type: integer
          default: 60
      - name: environment
        in: query
        description: Only reviewed merchant listings are returned. inventoryStatus is explicit; unknown inventory requires fresh supplier confirmation before quoting.
        schema:
          type: string
          enum:
          - production
          default: production
      - name: cursor
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Product results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiProductSearchResponse'
        '402':
          $ref: '#/components/responses/PaymentRequired'
      tags:
      - Products
  /v1/products/{sku}:
    get:
      operationId: getProduct
      summary: Get a complete product JSON-LD document
      parameters:
      - name: sku
        in: path
        required: true
        schema:
          type: string
      - name: environment
        in: query
        description: Only the approved merchant catalog is available; withdrawn listings return 404.
        schema:
          type: string
          enum:
          - production
          default: production
      responses:
        '200':
          description: Product detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiProductResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '402':
          $ref: '#/components/responses/PaymentRequired'
      tags:
      - Products
components:
  responses:
    PaymentRequired:
      description: An x402 payment is required for this query
      headers:
        PAYMENT-REQUIRED:
          schema:
            type: string
          description: Base64url-encoded x402 v2 payment required object
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              error:
                type: object
                properties:
                  code:
                    type: string
                    const: payment_required
                  paymentRequirements:
                    type: object
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ApiProductResponse:
      type: object
      required:
      - status
      - data
      - error
      properties:
        status:
          type: string
          const: ok
        data:
          $ref: '#/components/schemas/Product'
        error:
          type: 'null'
    ApiProductSearchResponse:
      type: object
      required:
      - status
      - data
      - error
      properties:
        status:
          type: string
          const: ok
        data:
          $ref: '#/components/schemas/ProductSearchResponse'
        error:
          type: 'null'
    ProductSearchResponse:
      type: object
      required:
      - items
      - nextCursor
      - queryCost
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        nextCursor:
          type:
          - string
          - 'null'
        queryCost:
          type: object
          properties:
            amount:
              type: string
            currency:
              type: string
    Error:
      type: object
      required:
      - status
      - data
      - error
      properties:
        status:
          type: string
          const: error
        data:
          type: 'null'
        error:
          type: object
          required:
          - code
          - message
          - requestId
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string
    Product:
      type: object
      required:
      - sku
      - name
      - material
      - size
      - moq
      - minOrderQuantity
      - price
      - inventory
      - leadTimeDays
      - supplierQualifications
      - dataFreshness
      properties:
        '@context':
          type: string
          const: https://schema.org
        '@type':
          type: string
          const: Product
        sku:
          type: string
        gtin:
          type: string
        name:
          type: string
        material:
          type: string
        size:
          type: string
        moq:
          type: integer
          minimum: 100
          description: Minimum order quantity in purchasable units
        minOrderQuantity:
          type: integer
          minimum: 100
          description: Alias of moq
        price:
          type: object
          properties:
            amount:
              type: number
            currency:
              type: string
        inventory:
          type:
          - integer
          - 'null'
          minimum: 0
          description: Null when the latest supplier snapshot has not confirmed stock
        inventoryStatus:
          type: string
          enum:
          - confirmed
          - unknown
        leadTimeDays:
          type: integer
          minimum: 0
        supplierQualifications:
          type: array
          items:
            type: string
        dataFreshness:
          type: string
          format: date-time
        isTestData:
          type: boolean
          deprecated: true
          description: Internal test-data marker. Public catalog responses only contain approved merchant records.
        dataEnvironment:
          type: string
          enum:
          - production
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    adminReviewKey:
      type: apiKey
      in: header
      name: X-Admin-Key