{
  "openapi": "3.1.0",
  "info": {
    "title": "Buyary Product Intelligence API",
    "version": "1.0.0",
    "description": "Synthesized product intelligence over Buyary's published catalog. The same service is exposed over remote MCP at https://services.buyary.com/mcp/ with identical response bodies."
  },
  "servers": [
    {
      "url": "https://services.buyary.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/product-intelligence": {
      "get": {
        "summary": "Product intelligence for a single product",
        "operationId": "getProductIntelligence",
        "parameters": [
          {
            "name": "product_name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "detail",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "full",
                "compact"
              ],
              "default": "full"
            },
            "description": "compact drops long-form prose fields; the shape is otherwise identical."
          }
        ],
        "responses": {
          "200": {
            "description": "The lookup ran - including found:false (limited coverage), which is a 200, not an error.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ProductIntelligence"
                    },
                    {
                      "$ref": "#/components/schemas/LimitedCoverage"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing product_name or unknown detail value."
          },
          "401": {
            "description": "Missing, malformed, revoked, or expired key."
          },
          "429": {
            "description": "Rate limited (120 requests/minute/key during the preview)."
          }
        }
      }
    },
    "/v1/product-intelligence/batch": {
      "post": {
        "summary": "Up to 5 products in one call",
        "operationId": "getProductIntelligenceBatch",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "product_names"
                ],
                "properties": {
                  "product_names": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results in input order; each entry is exactly the single-call shape. One miss never fails the batch.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "$ref": "#/components/schemas/ProductIntelligence"
                          },
                          {
                            "$ref": "#/components/schemas/LimitedCoverage"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Batch outside 1-5 names."
          },
          "401": {
            "description": "Missing, malformed, revoked, or expired key."
          },
          "429": {
            "description": "A batch of N counts as N lookups; one that would exceed your remaining budget fails before any lookups run."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Self-issued key from the dashboard; shown once at creation."
      }
    },
    "schemas": {
      "ProductIntelligence": {
        "type": "object",
        "properties": {
          "found": {
            "const": true
          },
          "product_name": {
            "type": "string"
          },
          "brand": {
            "type": "string"
          },
          "headline": {
            "type": "string"
          },
          "summary": {
            "type": "string",
            "description": "Long-form synthesized verdict (omitted in compact)."
          },
          "buyary_score": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "dimension_scores": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "dimension": {
                  "type": "string"
                },
                "score": {
                  "type": "number"
                },
                "summary": {
                  "type": "string"
                }
              }
            }
          },
          "feature_scores": {
            "type": "array",
            "description": "All 27 criteria across 7 dimensions.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "score": {
                  "type": "number"
                }
              }
            }
          },
          "highlights": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                }
              }
            }
          },
          "considerations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                }
              }
            }
          },
          "source_consensus": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "source_type": {
                  "type": "string"
                },
                "score": {
                  "type": "number"
                },
                "summary": {
                  "type": "string"
                }
              }
            }
          },
          "offers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "retailer_name": {
                  "type": "string"
                },
                "price": {
                  "type": "number"
                },
                "price_as_of": {
                  "type": "string",
                  "format": "date-time"
                },
                "buy_url": {
                  "type": "string",
                  "description": "Tracked, monetizable purchase link."
                }
              }
            }
          },
          "starting_price_usd": {
            "type": [
              "number",
              "null"
            ]
          },
          "source_count": {
            "type": "integer"
          },
          "resolution": {
            "type": "object",
            "properties": {
              "confidence": {
                "type": "number"
              },
              "other_matches": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "match_score": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LimitedCoverage": {
        "type": "object",
        "description": "Returned when no catalog product confidently matches - a suggestion, never a wrong product.",
        "properties": {
          "found": {
            "const": false
          },
          "other_matches": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "match_score": {
                  "type": "number"
                }
              }
            }
          }
        }
      }
    }
  }
}