openapi: 3.1.0
info:
  title: embals.es Public Data API
  version: "1.0.0"
  summary: Datos abiertos sobre el estado de los embalses en España.
  description: |
    API pública de solo lectura que expone el estado actual e histórico de
    los embalses españoles, agregado por comunidad autónoma, provincia y
    cuenca hidrográfica, junto con lecturas en tiempo casi real desde los
    SAIH de las confederaciones hidrográficas.

    Datos publicados bajo licencia Creative Commons BY 4.0.
  contact:
    name: embals.es
    url: https://embals.es/info
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://volcjmdnsxfuekvehwte.supabase.co/functions/v1
    description: Producción
externalDocs:
  description: Documentación humana
  url: https://embals.es/docs/api
components:
  securitySchemes:
    AnonKey:
      type: apiKey
      in: header
      name: apikey
      description: |
        Anon key pública del backend Supabase. Imprescindible en todas las
        peticiones. Se distribuye junto con la documentación humana.
security:
  - AnonKey: []
paths:
  /embalses-data-v2:
    get:
      operationId: getEmbalsesData
      summary: Datos agregados de embalses
      description: |
        Devuelve el estado actual de todos los embalses españoles agregado a
        nivel nacional, por comunidad autónoma, por provincia y por embalse
        individual, con metadatos de capacidad y porcentaje de llenado.
      responses:
        "200":
          description: Datos agregados
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /saih-data:
    get:
      operationId: getSaihData
      summary: Lecturas SAIH en tiempo casi real
      description: |
        Lecturas combinadas de los SAIH de Ebro, Duero, Júcar, Segura,
        Guadalquivir y Cantábrico. Frecuencia de actualización entre 1 y 24
        horas según cuenca.
      responses:
        "200":
          description: Lecturas SAIH
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /widget-data:
    get:
      operationId: getWidgetData
      summary: Payload compacto para widgets externos
      responses:
        "200":
          description: Datos para widgets
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /geojson-cache:
    get:
      operationId: getGeoJsonCache
      summary: GeoJSON cacheado de comunidades y provincias
      responses:
        "200":
          description: GeoJSON
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true