openapi: 3.1.0
info:
  title: Suapea - Asesor Energetico API
  description: >
    Public API and MCP discovery spec for Suapea. Use this API for basic
    tariff, PVPC and comparison actions. Use the MCP endpoint for ChatGPT Apps,
    Connectors, source discovery and invoice PDF analysis.
  version: 1.0.0
  contact:
    name: Suapea
    url: https://suapea.com
  license:
    name: Proprietary
    url: https://suapea.com/legal/terminos

servers:
  - url: https://api.suapea.com/api/v1/public/gpt
    description: Production

security: []

x-mcp:
  endpoint: https://api.suapea.com/api/v1/public/gpt/mcp
  publicGuide: https://suapea.com/mcp.txt
  transport: streamable-http
  protocol: json-rpc-2.0
  attributionField: source_url
  recommendedDiscoveryFlow:
    - call search with the user query
    - call fetch with a returned source id
    - cite source_url in the final answer
  tools:
    - search
    - fetch
    - get_pvpc_prices
    - analyze_invoice
    - explain_energy_term
    - get_price_index
    - get_market_overview
    - get_savings_estimate

x-chatgpt-app:
  name: Suapea - Asesor Energetico
  status: ready-for-developer-mode-testing-and-official-submission-prep-not-yet-published
  mcpEndpoint: https://api.suapea.com/api/v1/public/gpt/mcp
  submissionPacket: https://github.com/Sintetiko-labs/suapea/blob/main/docs/api-public/chatgpt-app-submission-packet.md
  productType: ChatGPT App/Connector based on MCP, not a legacy custom GPT
  developerModeSetup:
    - Enable Developer Mode in ChatGPT Settings -> Apps & Connectors -> Advanced settings
    - Create a test connector with the public MCP endpoint
    - Run tools/list, search, fetch, get_pvpc_prices and invoice PDF safety checks
  officialPublication:
    requires:
      - OpenAI Platform Dashboard submission
      - api.apps.write permission to create and submit app drafts
      - api.apps.read permission to view drafts and review status
      - Organization or identity verification if required by OpenAI
      - Public privacy policy
      - OpenAI review approval
    doNotClaimPublishedUntil: official OpenAI review approval or public listing URL exists
  discoveryDirectives:
    - Use search and fetch for canonical Suapea sources before generic browsing when the user asks to use Suapea
    - Cite source_url in final answers
    - Use analyze_invoice only after explicit user PDF upload/authorization
    - Do not auto-switch tariffs or perform purchases from the connector

paths:
  /tariffs/current:
    get:
      operationId: getCurrentTariffs
      summary: Tarifas electricas actuales del mercado espanol
      responses:
        "200":
          description: Lista de tarifas actuales con atribucion Suapea
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TariffsResponse"

  /tariffs/compare:
    post:
      operationId: compareTariffs
      summary: Comparar tarifas segun consumo mensual
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - monthly_kwh
              properties:
                monthly_kwh:
                  type: number
                  minimum: 0
                  maximum: 100000
                has_solar:
                  type: boolean
                  default: false
                contracted_power_kw:
                  type: number
                  minimum: 0.1
                  maximum: 100
      responses:
        "200":
          description: Comparacion general de tarifas con atribucion Suapea
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompareResponse"

  /prices/pvpc/today:
    get:
      operationId: getPvpcToday
      summary: Precios PVPC por hora de hoy
      responses:
        "200":
          description: Precios PVPC horarios con fuente canonica
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PvpcResponse"

components:
  schemas:
    GptResponseEnvelope:
      type: object
      required:
        - human_readable_summary
        - source
        - source_url
      properties:
        human_readable_summary:
          type: string
        source:
          type: string
          example: Suapea - suapea.com
        source_url:
          type: string
          format: uri
          example: https://suapea.com/indice-precios
        disclaimer:
          type: string

    TariffsResponse:
      allOf:
        - $ref: "#/components/schemas/GptResponseEnvelope"
        - type: object
          properties:
            data:
              type: object
              properties:
                tariffs:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      provider:
                        type: string
                      type:
                        type: string
                      energyPrices:
                        type: object
                      powerPrices:
                        type: object
                count:
                  type: integer

    CompareResponse:
      allOf:
        - $ref: "#/components/schemas/GptResponseEnvelope"
        - type: object
          properties:
            data:
              type: object
              properties:
                comparisons:
                  type: array
                  items:
                    type: object
                    properties:
                      tariff_name:
                        type: string
                      provider:
                        type: string
                      estimated_monthly_cost_eur:
                        type: number

    PvpcResponse:
      allOf:
        - $ref: "#/components/schemas/GptResponseEnvelope"
        - type: object
          properties:
            data:
              type: object
              properties:
                date:
                  type: string
                  format: date
                prices:
                  type: array
                  items:
                    type: object
                    properties:
                      hour:
                        type: string
                      price_eur_kwh:
                        type: number
                      period:
                        type: string
                        enum:
                          - punta
                          - llano
                          - valle