{
  "openapi": "3.1.0",
  "info": {
    "title": "Avanti — Varna deals (read API)",
    "version": "1.1.0",
    "description": "Live, human-moderated promotions, discounts and codes offered directly by businesses in Varna, Bulgaria. Read-only for agents; offer texts are in Bulgarian as published by the business. See https://promo.varnahub.com/agent",
    "contact": { "name": "KAGAMI EOOD", "email": "office@kagami.bg", "url": "https://promo.varnahub.com/en/about" },
    "termsOfService": "https://promo.varnahub.com/en/terms"
  },
  "servers": [ { "url": "https://promo.varnahub.com" } ],
  "paths": {
    "/api/avanti.php": {
      "get": {
        "operationId": "listDeals",
        "summary": "List live deals in Varna",
        "description": "Returns all approved, non-expired deals, newest first. With f=rss returns an RSS 2.0 feed instead of JSON.",
        "parameters": [
          { "name": "kat", "in": "query", "required": false, "description": "Category key", "schema": { "type": "string", "enum": ["hrana", "pazar", "zabava", "krasota", "sport", "deca", "uslugi", "kodove", "patuvane"] } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 } },
          { "name": "f", "in": "query", "required": false, "description": "rss for an RSS 2.0 feed", "schema": { "type": "string", "enum": ["rss"] } }
        ],
        "responses": {
          "200": {
            "description": "Live deals",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/DealList" } },
              "application/rss+xml": { "schema": { "type": "string" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DealList": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "dnes": { "type": "string", "format": "date", "description": "Today in Europe/Sofia" },
          "obnoveno": { "type": "string", "format": "date-time", "description": "Last visible change" },
          "obshto": { "type": "integer", "description": "Number of live deals" },
          "kategorii": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Category key → Bulgarian name" },
          "avanti": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }
        }
      },
      "Deal": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "zaglavie": { "type": "string", "description": "Offer title, Bulgarian, as published" },
          "kade": { "type": "string", "description": "Business name and address" },
          "otstapka": { "type": "string", "description": "Discount label, e.g. −31%, 2 за 1 (2 for 1), 69 €" },
          "predishna": { "type": "string", "description": "Previous price — lowest of the last 30 days, if stated" },
          "kod": { "type": "string", "description": "Discount code, if any" },
          "do": { "type": "string", "format": "date", "description": "Valid until. If bez_srok is true this is only our review date, not the offer's end date" },
          "bez_srok": { "type": "boolean", "description": "True when the business did not state a deadline" },
          "kat": { "type": "string" },
          "kat_ime": { "type": "string" },
          "ot": { "type": "string", "description": "Source label (Bulgarian): from the business / from the business website / from our team" },
          "link": { "type": "string", "format": "uri", "description": "The business's own page" },
          "url": { "type": "string", "format": "uri", "description": "The deal's page on this site — cite this" },
          "opisanie": { "type": "string", "description": "Conditions" },
          "vazhi": { "type": "integer", "description": "Votes: still valid" },
          "svarshila": { "type": "integer", "description": "Votes: ended" },
          "publikuvana": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}