{
  "openapi": "3.1.0",
  "info": {
    "title": "QuoteMatch API",
    "version": "1.7.0",
    "description": "Audit product catalogs and convert natural-language RFQs into catalog-bound quote lines with confidence scores, stock checks and deterministic totals. QuoteMatch returns drafts for human review and never invents catalog prices.",
    "termsOfService": "https://quotematch-api.quotematch-api.workers.dev/terms",
    "contact": {
      "name": "QuoteMatch support",
      "url": "https://t.me/QuoteMatchAssistantBot"
    },
    "x-thumbnail": "https://quotematch-api.quotematch-api.workers.dev/logo.png"
  },
  "externalDocs": {
    "description": "Developer quick start",
    "url": "https://quotematch-api.quotematch-api.workers.dev/developers"
  },
  "servers": [
    {
      "url": "https://quotematch.p.rapidapi.com",
      "description": "RapidAPI production gateway"
    }
  ],
  "tags": [
    {
      "name": "Status",
      "description": "Availability checks without an AI request."
    },
    {
      "name": "Catalog",
      "description": "Deterministic catalog validation and normalization without an AI request."
    },
    {
      "name": "Quotes",
      "description": "Catalog matching and review-ready quote calculations."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "Status"
        ],
        "operationId": "getHealth",
        "summary": "Check API availability",
        "responses": {
          "200": {
            "description": "API is available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                },
                "example": {
                  "status": "ok",
                  "service": "quotematch-api",
                  "version": "1.7.0"
                }
              }
            }
          }
        }
      }
    },
    "/v1/catalog-audit": {
      "post": {
        "tags": [
          "Catalog"
        ],
        "operationId": "auditCatalog",
        "summary": "Validate and normalize a product catalog",
        "description": "Checks required fields, numeric limits, duplicate SKUs and names, alias collisions, unsupported fields and missing matching metadata. This deterministic endpoint does not use AI tokens.",
        "security": [
          {
            "RapidApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-RapidAPI-Host",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "quotematch.p.rapidapi.com"
            },
            "example": "quotematch.p.rapidapi.com"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CatalogAuditRequest"
              },
              "example": {
                "catalog": [
                  {
                    "sku": "USB-C-BLK-1M",
                    "name": "USB-C Cable 1m Black",
                    "unit_price": 8.5,
                    "stock": 40,
                    "description": "Braided 60W USB-C charging cable.",
                    "aliases": [
                      "black type-c cable",
                      "usb c cable 1m"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Catalog audit completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogAuditResult"
                },
                "example": {
                  "request_id": "737869bb-3645-470b-93d2-8012292dd29f",
                  "status": "ready",
                  "ready_for_quote_match": true,
                  "summary": {
                    "items_received": 1,
                    "normalized_items": 1,
                    "errors": 0,
                    "warnings": 0,
                    "suggestions": 0
                  },
                  "issues": [],
                  "normalized_catalog": [
                    {
                      "sku": "USB-C-BLK-1M",
                      "name": "USB-C Cable 1m Black",
                      "unit_price": 8.5,
                      "stock": 40,
                      "description": "Braided 60W USB-C charging cable.",
                      "aliases": [
                        "black type-c cable",
                        "usb c cable 1m"
                      ]
                    }
                  ],
                  "disclaimer": "Catalog Audit checks structure and common quality risks. Review prices, stock and product identity before using the normalized catalog."
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds the 250 KB limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "RapidAPI plan quota or rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/quote-match": {
      "post": {
        "tags": [
          "Quotes"
        ],
        "operationId": "createQuoteDraft",
        "summary": "Match an RFQ to a catalog and calculate a draft quote",
        "description": "Extracts requested products and quantities, matches only supplied SKUs, uses only catalog prices, calculates monetary totals in code, and flags uncertain or stock-conflict lines for review.",
        "security": [
          {
            "RapidApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-RapidAPI-Host",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "quotematch.p.rapidapi.com"
            },
            "example": "quotematch.p.rapidapi.com"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              },
              "example": {
                "inquiry": "Need 12 black USB-C cables",
                "catalog": [
                  {
                    "sku": "USB-C-BLK-1M",
                    "name": "USB-C Cable 1m Black",
                    "unit_price": 8.5,
                    "stock": 40,
                    "aliases": [
                      "black type-c cable"
                    ]
                  }
                ],
                "settings": {
                  "currency": "USD",
                  "tax_rate": 0.06,
                  "confidence_threshold": 0.82
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Draft quote generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteResult"
                },
                "example": {
                  "request_id": "e41f1428-36dd-42b3-9784-6f83e9876f1d",
                  "currency": "USD",
                  "lines": [
                    {
                      "requested_text": "12 black USB-C cables",
                      "requested_quantity": 12,
                      "matched_sku": "USB-C-BLK-1M",
                      "matched_name": "USB-C Cable 1m Black",
                      "unit_price": 8.5,
                      "line_total": 102,
                      "confidence": 0.98,
                      "reason": "Exact product, color and length match.",
                      "requires_review": false
                    }
                  ],
                  "subtotal": 102,
                  "discount": 0,
                  "tax": 6.12,
                  "total": 108.12,
                  "requires_review": false,
                  "review_reasons": [],
                  "disclaimer": "Draft only. Review product matches, quantities, pricing, stock and tax before sending to a customer."
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds the 500 KB limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "RapidAPI plan quota or rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Upstream matching service failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "RapidApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-RapidAPI-Key",
        "description": "Subscriber key from your RapidAPI application. Keep it on your server."
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "service",
          "version"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "ok"
          },
          "service": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        }
      },
      "CatalogItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "sku",
          "name",
          "unit_price"
        ],
        "properties": {
          "sku": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "example": "USB-C-BLK-1M"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "example": "USB-C Cable 1m Black"
          },
          "unit_price": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000,
            "example": 8.5
          },
          "description": {
            "type": "string",
            "maxLength": 1000
          },
          "aliases": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "string",
              "maxLength": 100
            }
          },
          "stock": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000
          }
        }
      },
      "QuoteSettings": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "currency": {
            "type": "string",
            "pattern": "^[A-Za-z]{3}$",
            "example": "USD"
          },
          "tax_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "example": 0.06
          },
          "discount_rate": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "example": 0
          },
          "confidence_threshold": {
            "type": "number",
            "minimum": 0.5,
            "maximum": 1,
            "default": 0.82
          }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "inquiry",
          "catalog"
        ],
        "properties": {
          "inquiry": {
            "type": "string",
            "minLength": 1,
            "maxLength": 5000,
            "example": "Need 12 black USB-C cables"
          },
          "catalog": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/CatalogItem"
            }
          },
          "settings": {
            "$ref": "#/components/schemas/QuoteSettings"
          }
        }
      },
      "CatalogAuditRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "catalog"
        ],
        "properties": {
          "catalog": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "CatalogAuditIssue": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "severity",
          "message",
          "item_numbers"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning",
              "suggestion"
            ]
          },
          "message": {
            "type": "string"
          },
          "item_numbers": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            }
          },
          "skus": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "CatalogAuditSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items_received",
          "normalized_items",
          "errors",
          "warnings",
          "suggestions"
        ],
        "properties": {
          "items_received": {
            "type": "integer",
            "minimum": 0
          },
          "normalized_items": {
            "type": "integer",
            "minimum": 0
          },
          "errors": {
            "type": "integer",
            "minimum": 0
          },
          "warnings": {
            "type": "integer",
            "minimum": 0
          },
          "suggestions": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "CatalogAuditResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "status",
          "ready_for_quote_match",
          "summary",
          "issues",
          "normalized_catalog",
          "disclaimer"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "needs_attention"
            ]
          },
          "ready_for_quote_match": {
            "type": "boolean"
          },
          "summary": {
            "$ref": "#/components/schemas/CatalogAuditSummary"
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogAuditIssue"
            }
          },
          "normalized_catalog": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogItem"
            }
          },
          "disclaimer": {
            "type": "string"
          }
        }
      },
      "QuoteLine": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requested_text",
          "requested_quantity",
          "matched_sku",
          "matched_name",
          "unit_price",
          "line_total",
          "confidence",
          "reason",
          "requires_review"
        ],
        "properties": {
          "requested_text": {
            "type": "string"
          },
          "requested_quantity": {
            "type": "number"
          },
          "matched_sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "matched_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "unit_price": {
            "type": [
              "number",
              "null"
            ]
          },
          "line_total": {
            "type": [
              "number",
              "null"
            ]
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "reason": {
            "type": "string"
          },
          "requires_review": {
            "type": "boolean"
          }
        }
      },
      "QuoteResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "currency",
          "lines",
          "subtotal",
          "discount",
          "tax",
          "total",
          "requires_review",
          "review_reasons",
          "disclaimer"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "currency": {
            "type": "string"
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteLine"
            }
          },
          "subtotal": {
            "type": "number"
          },
          "discount": {
            "type": "number"
          },
          "tax": {
            "type": "number"
          },
          "total": {
            "type": "number"
          },
          "requires_review": {
            "type": "boolean"
          },
          "review_reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "disclaimer": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    }
  }
}