{
  "openapi": "3.1.0",
  "info": {
    "title": "FuelAzores public prices and articles",
    "version": "1.0.0",
    "description": "FuelAzores is an independent guide to official maximum fuel prices in the Azores and Madeira, including Porto Santo. These are regional caps, not individual station quotes. One approved official source with an exact amount and effective date is sufficient. Conflicting or ambiguous official evidence stays under review. Reports cannot override or block valid official prices. No forecast is presented as an announced change. Petrol 98 is not covered. Amounts use integer thousandths of EUR per litre (priceMillsPerLitre); divide by 1000 for EUR/litre. Effective dates use the region's time zone. A last verified price can be retained while a later period is pending or under review: inspect pendingStatus and freshness before calling it current. generatedAt is retrieval time, not publisher or verification time. Preserve official source links, dates, and the FuelAzores citation URL. Missing data is unknown, never zero. History is paginated and coverage gaps do not imply an unchanged price."
  },
  "servers": [
    {
      "url": "https://www.fuelazores.com"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/prices": {
      "get": {
        "operationId": "get_fuel_prices",
        "summary": "Read the latest verified and confirmed upcoming official maximum fuel prices, effective dates, review/freshness status, and sources. Optionally choose a region and fuel.",
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "azores",
                "madeira"
              ],
              "description": "Region whose official maximum prices to read."
            }
          },
          {
            "name": "fuel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "petrol95",
                "diesel",
                "agriculturalDiesel",
                "fishingDiesel",
                "marineDiesel",
                "markedDiesel"
              ],
              "description": "Exact regulated fuel category. Specialist fuels are not interchangeable with road diesel."
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv",
                "markdown"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public data. Inspect freshness, coverage and review state before citing prices.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid, unsupported, unknown or repeated parameters."
          },
          "404": {
            "description": "No matching article."
          },
          "429": {
            "description": "Shared dynamic-route limit: 120 requests/minute/IP per edge region. Honor Retry-After if present; otherwise wait at least 60 seconds. Edge response may be plain text."
          },
          "503": {
            "description": "Upstream unavailable; retry after 60 seconds. No substitute prices are returned."
          }
        }
      }
    },
    "/api/v1/history": {
      "get": {
        "operationId": "get_price_history",
        "summary": "Read a bounded page of verified historical official fuel prices. Follow nextCursor until isDone; gaps mean missing evidence, not unchanged prices.",
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "azores",
                "madeira"
              ],
              "description": "Region whose official maximum prices to read."
            }
          },
          {
            "name": "fuel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "petrol95",
                "diesel",
                "agriculturalDiesel",
                "fishingDiesel",
                "marineDiesel",
                "markedDiesel"
              ],
              "description": "Exact regulated fuel category. Specialist fuels are not interchangeable with road diesel."
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 2000,
              "maximum": 2100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4096
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv",
                "markdown"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public data. Inspect freshness, coverage and review state before citing prices.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid, unsupported, unknown or repeated parameters."
          },
          "404": {
            "description": "No matching article."
          },
          "429": {
            "description": "Shared dynamic-route limit: 120 requests/minute/IP per edge region. Honor Retry-After if present; otherwise wait at least 60 seconds. Edge response may be plain text."
          },
          "503": {
            "description": "Upstream unavailable; retry after 60 seconds. No substitute prices are returned."
          }
        }
      }
    },
    "/api/v1/articles": {
      "get": {
        "operationId": "find_fuel_articles",
        "summary": "Find Portuguese and English guides to Azores and Madeira fuel prices, official sources, regional comparisons, refill calculations and using FuelAzores. Use an article id and language to retrieve its complete Markdown. Dated examples are not live prices.",
        "parameters": [
          {
            "name": "language",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pt",
                "en"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 150
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "azores",
                "madeira",
                "comparison",
                "evidence",
                "refill",
                "fuelazores"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public data. Inspect freshness, coverage and review state before citing prices.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid, unsupported, unknown or repeated parameters."
          },
          "404": {
            "description": "No matching article."
          },
          "429": {
            "description": "Shared dynamic-route limit: 120 requests/minute/IP per edge region. Honor Retry-After if present; otherwise wait at least 60 seconds. Edge response may be plain text."
          },
          "503": {
            "description": "Upstream unavailable; retry after 60 seconds. No substitute prices are returned."
          }
        }
      }
    }
  }
}