{
  "openapi": "3.1.0",
  "info": {
    "title": "Boleron EU Agentic Discovery API",
    "description": "Read-only discovery feed for AI agents. Lists every supported European insurance market, the live comparison pages per product, and per-offer metadata (links, documents, last-verified dates). One URL per locale, with three payload sizes selectable via the detail_level query parameter.",
    "version": "1.1.0",
    "contact": {
      "name": "Boleron EU",
      "url": "https://boleron.eu"
    }
  },
  "servers": [
    {
      "url": "https://boleron.eu/api/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/discover/{locale}": {
      "get": {
        "summary": "Discover insurance markets, comparisons and offers for a given locale",
        "operationId": "discover",
        "parameters": [
          {
            "name": "locale",
            "in": "path",
            "required": true,
            "description": "BCP-47-style UI locale. One of the 22 supported values.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "bg",
                "ro",
                "de",
                "sk",
                "gr",
                "fr",
                "nl",
                "hr",
                "cs",
                "da",
                "et",
                "fi",
                "hu",
                "it",
                "lv",
                "lt",
                "pl",
                "pt",
                "sl",
                "es",
                "sv"
              ]
            }
          },
          {
            "name": "detail_level",
            "in": "query",
            "required": false,
            "description": "Controls payload size and depth.\n\n- `summary`: index only — market identifiers, currency, insurer count, product slugs, and comparison counts. No comparison offers, no source citations, no per-market prose. Best for cheap polling and catalogue enumeration.\n- `standard` (default): adds per-market prose, available locales, comparison-page URLs, and per-offer entries with insurer name, summary, last-verified date and offer URL. Skips deep offer detail (direct-payment policy, highlights, whereToBuy, documents).\n- `full`: everything in `standard` plus source citations on markets, plus per-offer direct-payment policy, highlights, whereToBuy links and documents (IPID / terms / prospectus URLs). Largest payload.",
            "schema": {
              "type": "string",
              "enum": [
                "summary",
                "standard",
                "full"
              ],
              "default": "standard"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery payload for the requested locale and detail level.",
            "headers": {
              "Cache-Control": {
                "description": "CDN cacheability: public, 1h fresh, 24h stale-while-revalidate.",
                "schema": {
                  "type": "string"
                }
              },
              "Access-Control-Allow-Origin": {
                "description": "Always `*` — cross-origin agent access is permitted.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiscoverResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid detail_level value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Locale not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "options": {
        "summary": "CORS preflight",
        "operationId": "discoverPreflight",
        "parameters": [
          {
            "name": "locale",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight allowed."
          }
        }
      }
    },
    "/discover/{locale}/{country}": {
      "get": {
        "summary": "Discover a single insurance market, scoped to one country",
        "description": "Same payload shape as /discover/{locale}, filtered to a single country. Useful for agents that only need one market without fetching the full discovery payload.",
        "operationId": "discoverCountry",
        "parameters": [
          {
            "name": "locale",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "path",
            "required": true,
            "description": "Country slug, e.g. \"germany\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "detail_level",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "summary",
                "standard",
                "full"
              ],
              "default": "standard"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery payload scoped to the requested country.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiscoverResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid detail_level value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Locale or country not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "options": {
        "summary": "CORS preflight",
        "operationId": "discoverCountryPreflight",
        "responses": {
          "204": {
            "description": "Preflight allowed."
          }
        }
      }
    },
    "/discover/{locale}/{country}/{product}": {
      "get": {
        "summary": "Discover a single insurance market, scoped to one country and product",
        "description": "Same payload shape as /discover/{locale}, filtered to a single (country, product) pair. The narrowest discovery payload available.",
        "operationId": "discoverCountryProduct",
        "parameters": [
          {
            "name": "locale",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "product",
            "in": "path",
            "required": true,
            "description": "Product slug, e.g. \"mtpl\", \"casco\", \"travel\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "detail_level",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "summary",
                "standard",
                "full"
              ],
              "default": "standard"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery payload scoped to the requested country and product.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiscoverResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid detail_level value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Locale, country, or product not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "options": {
        "summary": "CORS preflight",
        "operationId": "discoverCountryProductPreflight",
        "responses": {
          "204": {
            "description": "Preflight allowed."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DiscoverResponse": {
        "type": "object",
        "required": [
          "meta",
          "markets",
          "comparisons"
        ],
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "markets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Market"
            }
          },
          "comparisons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Comparison"
            }
          }
        }
      },
      "Meta": {
        "type": "object",
        "required": [
          "generatedAt",
          "locale",
          "detailLevel",
          "marketCount",
          "comparisonCount",
          "offerCount"
        ],
        "properties": {
          "generatedAt": {
            "type": "string",
            "description": "Latest last-verified timestamp across markets and offers in this payload (ISO 8601 date or date-time)."
          },
          "locale": {
            "type": "string"
          },
          "detailLevel": {
            "type": "string",
            "enum": [
              "summary",
              "standard",
              "full"
            ]
          },
          "marketCount": {
            "type": "integer",
            "minimum": 0
          },
          "comparisonCount": {
            "type": "integer",
            "minimum": 0
          },
          "offerCount": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "Market": {
        "type": "object",
        "required": [
          "country",
          "countryName",
          "locale",
          "lastVerified",
          "currency",
          "insurerCount",
          "marketProducts",
          "liveComparisonProducts",
          "countryUrl"
        ],
        "properties": {
          "country": {
            "type": "string",
            "description": "Country slug, e.g. \"germany\"."
          },
          "countryName": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "lastVerified": {
            "type": "string",
            "description": "Most recent verification of this market's data (ISO 8601)."
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code."
          },
          "insurerCount": {
            "type": "integer",
            "minimum": 0
          },
          "marketProducts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All product slugs offered in this market (may exceed liveComparisonProducts)."
          },
          "liveComparisonProducts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Product slugs with a published comparison page in this locale."
          },
          "countryUrl": {
            "type": "string",
            "format": "uri"
          },
          "availableLocales": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Omitted at detail_level=summary."
          },
          "languageCode": {
            "type": "string",
            "description": "Omitted at detail_level=summary."
          },
          "summary": {
            "type": "string",
            "description": "Localized market-overview prose. Omitted at detail_level=summary."
          },
          "comparisonPages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonPage"
            },
            "description": "Omitted at detail_level=summary."
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            },
            "description": "Source citations. Returned only at detail_level=full."
          }
        }
      },
      "ComparisonPage": {
        "type": "object",
        "required": [
          "product",
          "url"
        ],
        "properties": {
          "product": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Source": {
        "type": "object",
        "required": [
          "label"
        ],
        "properties": {
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Comparison": {
        "type": "object",
        "required": [
          "country",
          "product",
          "comparisonUrl",
          "offerCount"
        ],
        "properties": {
          "country": {
            "type": "string"
          },
          "product": {
            "type": "string"
          },
          "comparisonUrl": {
            "type": "string",
            "format": "uri"
          },
          "offerCount": {
            "type": "integer",
            "minimum": 0
          },
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Offer"
            },
            "description": "Returned at detail_level=standard and detail_level=full."
          }
        }
      },
      "Offer": {
        "type": "object",
        "required": [
          "insurerSlug",
          "insurerName",
          "lastVerified",
          "offerUrl"
        ],
        "properties": {
          "insurerSlug": {
            "type": "string"
          },
          "insurerName": {
            "type": "string"
          },
          "lastVerified": {
            "type": "string",
            "description": "Most recent verification of this offer's terms (ISO 8601)."
          },
          "offerUrl": {
            "type": "string",
            "format": "uri"
          },
          "summary": {
            "type": "string"
          },
          "directPaymentPolicy": {
            "type": "string",
            "description": "Returned only at detail_level=full."
          },
          "highlights": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Returned only at detail_level=full."
          },
          "whereToBuy": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfferLink"
            },
            "description": "Returned only at detail_level=full."
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfferDocument"
            },
            "description": "Returned only at detail_level=full."
          }
        }
      },
      "OfferLink": {
        "type": "object",
        "required": [
          "label",
          "url"
        ],
        "properties": {
          "label": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "OfferDocument": {
        "type": "object",
        "required": [
          "label",
          "type",
          "url"
        ],
        "properties": {
          "label": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "Document type tag (e.g. \"IPID\", \"terms\", \"prospectus\")."
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "allowed": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}