BuyingMesh Admin API

openapi: 3.2.0
info:
  title: BuyingMesh Procurement Admin 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: Admin
paths:
  /v1/admin/applications:
    get:
      operationId: listMerchantApplicationsForReview
      summary: List merchant applications and review counts
      security:
      - adminReviewKey: []
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - received
          - under_review
          - approved
          - changes_requested
          - needs_info
          - rejected
      responses:
        '200':
          description: Review queue
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Admin
  /v1/admin/applications/{applicationId}:
    get:
      operationId: getMerchantApplicationForReview
      summary: Get an application and its submitted products
      security:
      - adminReviewKey: []
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Application detail
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Admin
    post:
      operationId: reviewMerchantApplication
      summary: Approve, reject or request changes for an application
      security:
      - adminReviewKey: []
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Admin-Key
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewAction'
      responses:
        '200':
          description: Review saved
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Admin
  /v1/admin/suppliers/{supplierId}:
    patch:
      operationId: updateSupplierProfile
      summary: Update reviewed supplier storefront metadata and credential review records
      security:
      - adminReviewKey: []
      parameters:
      - name: supplierId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                displayName:
                  type: string
                legalName:
                  type: string
                description:
                  type: string
                websiteUrl:
                  type: string
                  format: uri
                countryRegion:
                  type: string
                supplierType:
                  type: string
                categories:
                  type: array
                  items:
                    type: string
                credentials:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: Supplier profile updated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Admin
  /v1/admin/products:
    get:
      operationId: listMerchantProductsForReview
      summary: List submitted products for review
      security:
      - adminReviewKey: []
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending_review
          - approved
          - changes_requested
          - needs_info
          - rejected
      responses:
        '200':
          description: Product review queue
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Admin
  /v1/admin/traffic:
    get:
      operationId: getTrafficSummary
      summary: Get site, API and agent crawler traffic
      security:
      - adminReviewKey: []
      parameters:
      - name: days
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 90
          default: 14
      responses:
        '200':
          description: Traffic summary with agent signatures and recent edge events
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/SuccessEnvelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/TrafficSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Admin
  /v1/admin/products/{productId}:
    post:
      operationId: reviewMerchantProduct
      summary: Approve or request changes for a submitted product
      security:
      - adminReviewKey: []
      parameters:
      - name: productId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Admin-Key
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewAction'
      responses:
        '200':
          description: Review saved
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Admin
  /v1/admin/orders:
    get:
      operationId: adminListOrders
      summary: List persisted orders for the merchant console
      security:
      - adminReviewKey: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 50
      responses:
        '200':
          description: Order summaries and status counts
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Admin
  /v1/admin/catalog-quality:
    get:
      operationId: getCatalogQuality
      summary: Read catalog quality and quote readiness metrics
      security:
      - adminReviewKey: []
      responses:
        '200':
          description: Catalog quality summary
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Admin
  /v1/admin/test-catalog/cleanup:
    post:
      operationId: withdrawInternalTestCatalog
      summary: Preview or withdraw historical internal test listings
      description: Marks rows explicitly classified as internal test data as withdrawn and preserves them for audit. This operation never deletes product or merchant application records.
      security:
      - adminReviewKey: []
      parameters:
      - name: confirm
        in: query
        required: false
        schema:
          type: string
          enum:
          - WITHDRAW_INTERNAL_TEST_CATALOG
      responses:
        '200':
          description: Withdrawal preview or result
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Admin
  /v1/admin/suppliers/{supplierId}/notification-channel:
    get:
      operationId: getSupplierNotificationChannel
      summary: Read a supplier notification channel
      security:
      - adminReviewKey: []
      parameters:
      - name: supplierId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Supplier notification channel
      tags:
      - Admin
    patch:
      operationId: updateSupplierNotificationChannel
      summary: Configure a supplier webhook and notification email
      security:
      - adminReviewKey: []
      parameters:
      - name: supplierId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhookUrl:
                  type: string
                  format: uri
                webhookSecret:
                  type: string
                  minLength: 16
                notificationEmail:
                  type: string
                  format: email
      responses:
        '200':
          description: Supplier notification channel saved
      tags:
      - Admin
  /v1/admin/suppliers/{supplierId}/notifications:
    get:
      operationId: listSupplierNotifications
      summary: List supplier order notifications
      security:
      - adminReviewKey: []
      parameters:
      - name: supplierId
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100
      responses:
        '200':
          description: Supplier notification queue and delivery states
      tags:
      - Admin
components:
  schemas:
    ReviewAction:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - received
          - under_review
          - approved
          - changes_requested
          - needs_info
          - rejected
          - pending_review
        note:
          type: string
          maxLength: 1000
    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
    SuccessEnvelope:
      type: object
      required:
      - status
      - data
      - error
      properties:
        status:
          type: string
          const: ok
        data:
          type: object
        error:
          type: 'null'
    TrafficSummary:
      type: object
      required:
      - periodDays
      - totals
      - daily
      - funnel
      - agents
      - paths
      - recent
      properties:
        periodDays:
          type: integer
        totals:
          type: object
          properties:
            requests:
              type: integer
            agents:
              type: integer
            humans:
              type: integer
            apiClients:
              type: integer
        daily:
          type: array
          items:
            type: object
        funnel:
          type: array
          items:
            type: object
            properties:
              stage:
                type: string
              requests:
                type: integer
              last_seen:
                type:
                - string
                - 'null'
              sample:
                type: boolean
        agents:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              requests:
                type: integer
              last_seen:
                type: string
        paths:
          type: array
          items:
            type: object
        recent:
          type: array
          items:
            type: object
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Merchant authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    adminReviewKey:
      type: apiKey
      in: header
      name: X-Admin-Key