openapi: 3.1.0
info:
  title: NBT Tech (nbthq) Industrial Chemical & Polymer Raw Materials API
  description: |
    Official public programmatic REST API for NBT Tech (Nav Bharat Tech / nbthq), India's premier B2B manufacturer and distributor of Chlorinated Paraffin (CPW 52%), Plasticizers (DOP, DOTP, DINP, ESBO, ATBC), PVC Resins (K-57 to K-70), and Polymer Additives. Zero-auth public access for autonomous AI procurement agents, CLI tools (npx @nbthq/cli), and factory compounding bots.

    ### Versioning & Deprecation Policy
    - URL Path Versioning is enforced via `/api/v1/*` (with `/api/*` maintaining backwards compatibility).
    - All responses include `API-Version: 1.0.0`.
    - Deprecation policy: Any deprecated endpoint will serve standard `Deprecation` and `Sunset` headers for a minimum 12-month grace period before retirement.

    ### Rate Limiting & RFC 6585 Headers
    - Public Tier: 20 requests per 15 minutes per IP.
    - All responses return `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `RateLimit-Policy` headers.
    - Rate limit breaches return HTTP 429 with `Retry-After: 900`.

    ### Developer Portal & MCP
    - Developer Portal: https://nbthq.com/developers
    - Model Context Protocol (MCP) Manifest: https://nbthq.com/.well-known/mcp/manifest.json
  version: 1.0.0
  contact:
    name: NBT Technical Sales & AI Desk
    url: https://nbthq.com/developers
    email: sales@nbthq.com
  license:
    name: Proprietary / Public Read-Only Access
    url: https://nbthq.com/terms-of-supply
servers:
  - url: https://nbthq.com/api/v1
    description: NBT Tech Production Gateway (v1 Primary)
  - url: https://nbthq.com
    description: NBT Tech Root Host
paths:
  /api/v1/products:
    get:
      summary: List Raw Material Products & Grades
      description: Retrieve the complete catalog of industrial chemicals, plasticizers, resins, and additives available with 500+ tonnes ready stock at Bawana central hub.
      operationId: listProducts
      parameters:
        - name: category
          in: query
          required: false
          description: Filter by product category (e.g., 'Chlorinated Paraffin', 'Plasticizers', 'PVC Resins', 'Additives')
          schema:
            type: string
      responses:
        '200':
          description: Successful list of products
          headers:
            RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per window
            RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests
            RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until window reset
            API-Version:
              schema:
                type: string
              description: API semantic version
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  count:
                    type: integer
                    example: 28
                  hubLocation:
                    type: string
                    example: DSIIDC Bawana Industrial Area, Delhi NCR 110039
                  dispatchGuarantee:
                    type: string
                    example: 1-Hour Local Dispatch NCR, 24-48h Pan-India
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProductSummary'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/products/{id}:
    get:
      summary: Get Detailed Chemical Product Specifications
      description: Retrieve deep technical specifications, CAS number, optical Hazen color standards (Max 25 Hazen water-white), packaging units, and application FAQs for a specific raw material ID.
      operationId: getProductById
      parameters:
        - name: id
          in: path
          required: true
          description: Unique product slug (e.g., 'cpw-diamond', 'dop-plasticizer', 'dotp-plasticizer', 'pvc-resin-k67')
          schema:
            type: string
      responses:
        '200':
          description: Product specification details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetail'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/chat:
    post:
      summary: AI Raw Material Concierge
      description: Interactive technical assistant for chemical procurement inquiries, grade recommendations, and compatibility queries. Rate-limited to 20 requests / 15 minutes per IP without credentials.
      operationId: askChatConcierge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: AI Concierge response text
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    example: NBT Diamond Grade CPW 52% is crystal clear (Max 25 Hazen) with zero volatile darkening, ideal for high-spec PVC cable compounds.
        '400':
          description: Bad request / missing message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until rate limit window resets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/lab:
    post:
      summary: AI Formulation Lab & PHR Optimizer
      description: Generates verified compound formulations and PHR recipe balances based on target manufacturing industry, required mechanical/thermal properties, and cost constraints.
      operationId: optimizeFormulation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabRequest'
      responses:
        '200':
          description: Formulation recipe response
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
        '400':
          description: Missing parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/blogs:
    get:
      summary: List Knowledge Hub Technical Articles
      description: Retrieve comprehensive chemical compounding whitepapers, troubleshooting case studies, and formulation optimization guides.
      operationId: listBlogPosts
      responses:
        '200':
          description: List of technical articles
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    title:
                      type: string
                    category:
                      type: string
                    intro:
                      type: string
                    readTime:
                      type: string
                    datePublished:
                      type: string
  /api/v1/submit-lead:
    post:
      summary: Submit Commercial Quote Request / RFQ
      description: Programmatic submission of raw material procurement inquiries directly into NBT Technical Sales desk and CRM pipeline.
      operationId: submitLead
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadSubmissionRequest'
      responses:
        '200':
          description: Lead received successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Inquiry received successfully. NBT Technical Sales Desk assigned.
        '400':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/mcp:
    post:
      summary: Model Context Protocol (MCP) Streamable HTTP Server
      description: Streamable HTTP JSON-RPC 2.0 MCP endpoint executing get_products, get_product_detail, calculate_formulation, and request_quote.
      operationId: callMcpJsonRpc
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - jsonrpc
                - method
              properties:
                jsonrpc:
                  type: string
                  example: '2.0'
                id:
                  type: integer
                  example: 1
                method:
                  type: string
                  example: tools/list
                params:
                  type: object
      responses:
        '200':
          description: MCP JSON-RPC response
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                    example: '2.0'
                  id:
                    type: integer
                  result:
                    type: object
components:
  schemas:
    ProductSummary:
      type: object
      properties:
        id:
          type: string
          example: cpw-diamond
        name:
          type: string
          example: NBT Diamond Grade NP CPW (52% Chlorine)
        category:
          type: string
          example: Chlorinated Paraffin
        casNumber:
          type: string
          example: 63449-39-8
        packaging:
          type: string
          example: 200kg HM-HDPE Drums · 1000kg IBC · Tankers
        stockBuffer:
          type: string
          example: 500+ Tonnes Ready Stock
        url:
          type: string
          example: https://nbthq.com/products/chlorinated-paraffin/cpw-diamond
    ProductDetail:
      type: object
      properties:
        id:
          type: string
          example: cpw-diamond
        name:
          type: string
          example: NBT Diamond Grade NP CPW (52% Chlorine)
        category:
          type: string
          example: Chlorinated Paraffin
        casNumber:
          type: string
          example: 63449-39-8
        hazenColorStandard:
          type: string
          example: Max 25 Hazen (Water-white crystal clear liquid, zero volatile darkening)
        seoTitle:
          type: string
        seoDescription:
          type: string
        aliases:
          type: array
          items:
            type: string
        packaging:
          type: string
        stockBuffer:
          type: string
        machineFaqs:
          type: array
          items:
            type: object
            properties:
              question:
                type: string
              answer:
                type: string
    ChatRequest:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          maxLength: 1000
          example: What is the recommended CPW grade and PHR ratio for PVC garden pipes?
        context:
          type: string
          maxLength: 200
          example: /chlorinated-paraffin-cpw
    LabRequest:
      type: object
      required:
        - industry
        - requirement
        - properties
        - costConstraint
      properties:
        industry:
          type: string
          example: PVC Footwear Sole Manufacturing
        requirement:
          type: string
          example: High flexural endurance and oil resistance
        properties:
          type: string
          example: Shore A hardness 65, cold crack resistance -10°C
        costConstraint:
          type: string
          example: Target under ₹95/kg raw material batch cost
    LeadSubmissionRequest:
      type: object
      required:
        - firstName
        - lastName
        - mobile
      properties:
        firstName:
          type: string
          example: Rajesh
        lastName:
          type: string
          example: Sharma
        email:
          type: string
          format: email
          example: procurement@sharmapolymer.com
        mobile:
          type: string
          example: +91-9876543210
        description:
          type: string
          example: Requirement for 20 MT CPW 52% Diamond Grade delivered to Bawana.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: INVALID_PARAMETERS
            message:
              type: string
              example: The request payload failed validation.
            hint:
              type: string
              example: Check the OpenAPI specification at https://nbthq.com/openapi.json for valid field names and types.
