{
  "openapi": "3.1.0",
  "info": {
    "title": "Breathelo Agent API",
    "version": "1.0.0",
    "summary": "Read-only access to power station usable-capacity data and the site's explainer articles.",
    "description": "Breathelo tracks consumer power equipment and publishes the arithmetic most spec sheets omit: a 2,048Wh battery delivers about 1,567Wh to your appliances after the depth-of-discharge reserve and inverter loss. This API exposes that same arithmetic and the articles that explain it. All endpoints are read-only, require no authentication, and return bounded result sets.",
    "contact": {
      "url": "https://breathelo.com/about/"
    },
    "license": {
      "name": "Content is free to read and cite with attribution",
      "identifier": "CC-BY-4.0"
    }
  },
  "servers": [
    {
      "url": "https://breathelo.com"
    }
  ],
  "paths": {
    "/api/agent": {
      "get": {
        "operationId": "queryAgentApi",
        "summary": "Query products or articles",
        "description": "One endpoint with an `action` switch. Calling it with no parameters returns a self-describing help document listing every action and filter.",
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": false,
            "description": "Which dataset to query. Omit for the help document.",
            "schema": {
              "type": "string",
              "enum": [
                "help",
                "products",
                "product",
                "articles"
              ],
              "default": "help"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "description": "Filter products by equipment category. Only meaningful when action=products.",
            "schema": {
              "type": "string",
              "enum": [
                "power",
                "dehumidifier",
                "airpurifier",
                "camera",
                "audio",
                "smartlock",
                "wearable",
                "thermal",
                "glasses",
                "drone",
                "flashlight"
              ]
            }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "Filter by brand key, lowercase and hyphenated as used in page URLs (e.g. anker, bluetti, ecoflow).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "description": "Maximum price in US dollars.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "minUsableWh",
            "in": "query",
            "description": "Minimum usable watt-hours. Usable capacity is nominal capacity times 0.9 depth of discharge times 0.85 inverter efficiency.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Result order. Default value sorts by cost per usable watt-hour, which is the site's core comparison — sorting by nominal capacity puts expensive low-efficiency units first.",
            "schema": {
              "type": "string",
              "enum": [
                "value",
                "capacity",
                "price"
              ],
              "default": "value"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of products to return. Capped at 50.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "asin",
            "in": "query",
            "description": "Amazon ASIN. Required when action=product. Case-insensitive.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter articles by section. Only meaningful when action=articles.",
            "schema": {
              "type": "string",
              "enum": [
                "specs",
                "sizing",
                "running-costs",
                "trade-offs"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful query. The exact shape depends on `action`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/HelpDocument"
                    },
                    {
                      "$ref": "#/components/schemas/ProductList"
                    },
                    {
                      "$ref": "#/components/schemas/ProductResult"
                    },
                    {
                      "$ref": "#/components/schemas/ArticleList"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown parameter, such as an unknown action or a missing ASIN.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "action=product with an ASIN this catalog does not track.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The dataset could not be loaded. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "required": [
          "asin",
          "name",
          "brand",
          "kind",
          "priceUsd",
          "page"
        ],
        "properties": {
          "asin": {
            "type": "string",
            "description": "Amazon ASIN, stable identifier across the site."
          },
          "name": {
            "type": "string"
          },
          "brand": {
            "type": "string"
          },
          "brandKey": {
            "type": "string",
            "description": "Lowercase brand slug used in /brands/<brandKey>/ URLs."
          },
          "page": {
            "type": "string",
            "format": "uri",
            "description": "The site's own page for this product, with the full arithmetic."
          },
          "kind": {
            "type": "string",
            "description": "Equipment category."
          },
          "priceUsd": {
            "type": "number",
            "description": "Price in US dollars as last read from the retailer."
          },
          "priceAsOf": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date the price was read. Null if never recorded."
          },
          "rating": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 1,
            "maximum": 5
          },
          "reviewCount": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "nominalWh": {
            "type": [
              "number",
              "null"
            ],
            "description": "Capacity printed on the box. Null for categories where capacity is not a parameter."
          },
          "usableWh": {
            "type": [
              "number",
              "null"
            ],
            "description": "Capacity that reaches your appliances. Null means genuinely unknown, never zero."
          },
          "acWatts": {
            "type": [
              "number",
              "null"
            ],
            "description": "Continuous AC output in watts."
          }
        }
      },
      "Article": {
        "type": "object",
        "required": [
          "slug",
          "category",
          "title",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "h1": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "answer": {
            "type": [
              "string",
              "null"
            ],
            "description": "The article's short answer paragraph, suitable for direct citation."
          },
          "sections": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Section headings in order."
          }
        }
      },
      "HelpDocument": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "base": {
            "type": "string",
            "format": "uri"
          },
          "actions": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ProductList": {
        "type": "object",
        "required": [
          "action",
          "total",
          "returned",
          "items"
        ],
        "properties": {
          "action": {
            "type": "string"
          },
          "filters": {
            "type": "object"
          },
          "total": {
            "type": "integer",
            "description": "Matches before limit was applied."
          },
          "returned": {
            "type": "integer"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          },
          "source": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ProductResult": {
        "type": "object",
        "required": [
          "action",
          "item"
        ],
        "properties": {
          "action": {
            "type": "string"
          },
          "item": {
            "$ref": "#/components/schemas/Product"
          },
          "source": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ArticleList": {
        "type": "object",
        "required": [
          "action",
          "total",
          "items"
        ],
        "properties": {
          "action": {
            "type": "string"
          },
          "filters": {
            "type": "object"
          },
          "total": {
            "type": "integer"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Article"
            }
          },
          "source": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine-readable code, e.g. asin_not_found."
          },
          "hint": {
            "type": "string",
            "description": "What a caller should try instead."
          }
        }
      }
    }
  }
}
