openapi: 3.0.0
info:
  title: Otark Forecast API
  description: API zum Abruf der ENWEX-Referenzindexe, die OES unter Lizenz der Enwex GmbH bereitstellt — stündliche Indexwerte je Liefertag, das Viertelstundenprofil des Tagesfahrplans für den folgenden Liefertag und die monatliche Langfristprognose. Die Indexdaten werden zur Vertragsabwicklung bereitgestellt; eine Verwendung darüber hinaus ist nicht gestattet.
  version: "1.0.0"
  contact: {}
servers:
  - url: https://api.otark.com
    description: Produktion
tags:
  - name: Indexes
    description: Die ENWEX-Referenzindexe ENWEX Solar DE und ENWEX Wind DE
  - name: Index values
    description: Stündliche Indexwerte je Liefertag, in Prozent der Nennleistung
  - name: Day schedule
    description: Das Viertelstundenprofil des Index für einen Liefertag
  - name: Long-term forecast
    description: Monatliche Indexprognose vom laufenden Monat bis zum Dezember des Folgejahres
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  parameters:
    LimitParam:
      name: limit
      in: query
      description: Höchstzahl der Einträge pro Seite
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    AfterParam:
      name: after
      in: query
      description: Cursor für die nächste Seite — den Wert `next_cursor` aus der vorherigen Antwort übergeben
      schema:
        type: string
        example: enwex-solar-de
    IndexIdParam:
      name: index_id
      in: path
      required: true
      description: Kennung des Index
      schema:
        type: string
        enum:
          - enwex-solar-de
          - enwex-wind-de
        example: enwex-solar-de
    DeliveryDateParam:
      name: delivery_date
      in: query
      description: "Liefertag (`YYYY-MM-DD`). Voreinstellung ist der zuletzt veröffentlichte Liefertag: ab 10:00 Uhr (Europe/Berlin) der Folgetag, davor der laufende Tag"
      schema:
        type: string
        format: date
        example: "2026-07-15"
    FromMonthParam:
      name: from_month
      in: query
      description: "Filter: erster einbezogener Monat (`YYYY-MM`). Voreinstellung ist der laufende Monat"
      schema:
        type: string
        pattern: "^\\d{4}-(0[1-9]|1[0-2])$"
        example: "2026-07"
    ToMonthParam:
      name: to_month
      in: query
      description: "Filter: letzter einbezogener Monat (`YYYY-MM`). Voreinstellung ist der Dezember des Folgejahres, das Ende des Prognosehorizonts"
      schema:
        type: string
        pattern: "^\\d{4}-(0[1-9]|1[0-2])$"
        example: "2027-12"
  headers:
    X-RateLimit-Limit:
      description: Höchstzahl der Anfragen je Zeitfenster
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Verbleibende Anfragen im laufenden Zeitfenster
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Sekunden, bis das Zeitfenster der Ratenbegrenzung zurückgesetzt wird
      schema:
        type: integer
  schemas:
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          description: Höchstzahl der Einträge pro Seite
          example: 10
        has_more:
          type: boolean
          description: Ob nach dem letzten gelieferten Eintrag weitere Einträge folgen
          example: false
        next_cursor:
          type: string
          nullable: true
          description: Cursor, der als Query-Parameter `after` übergeben wird, um die nächste Seite abzurufen. Null, wenn keine weiteren Seiten folgen.
          example: null
      required:
        - limit
        - has_more
        - next_cursor
    Problem:
      type: object
      description: Fehlerantwort nach [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457).
      properties:
        type:
          type: string
          format: uri
          description: Absolute URI, die die Fehlerklasse bezeichnet
          example: https://api.otark.com/errors/delivery_day_not_published
        title:
          type: string
          description: Kurze, lesbare Bezeichnung (bei gleicher Fehlerklasse unverändert)
          example: Delivery Day Not Published
        status:
          type: integer
          description: HTTP-Statuscode
          example: 404
        detail:
          type: string
          description: Lesbare Erläuterung dieses konkreten Falls
          example: No day schedule has been published for 2026-07-16 yet. The index for a delivery day is published at 10:00 (Europe/Berlin) on the preceding day.
        instance:
          type: string
          description: URI, die die konkrete Anfrage bezeichnet
          example: /v1/indexes/enwex-solar-de/day-schedule
        errors:
          type: array
          description: Feldbezogene Validierungsfehler (nur bei fehlgeschlagener Validierung)
          items:
            $ref: "#/components/schemas/ProblemFieldError"
      required:
        - type
        - title
        - status
    ProblemFieldError:
      type: object
      description: Ein einzelner feldbezogener Validierungsfehler
      properties:
        field:
          type: string
          description: JSON-Pfad des Feldes, das den Fehler ausgelöst hat
          example: delivery_date
        code:
          type: string
          description: "Maschinenlesbarer Fehlercode: `unknown_field`, `read_only_field`, `required`, `invalid_type`, `invalid_enum_value`, `invalid_format`, `invalid_literal`, `value_too_small`, `value_too_large` oder `validation_failed`"
          example: invalid_format
        message:
          type: string
          description: Lesbare Beschreibung des Fehlers
          example: "Invalid date. Expected YYYY-MM-DD, received '15.07.2026'"
      required:
        - code
        - message
    Index:
      type: object
      description: Ein ENWEX-Referenzindex. Es gibt zwei Indexe — ENWEX Solar DE und ENWEX Wind DE, veröffentlicht von der Enwex GmbH und von OES unter Lizenz bereitgestellt.
      properties:
        id:
          type: string
          description: Kennung des Index
          enum:
            - enwex-solar-de
            - enwex-wind-de
          example: enwex-solar-de
        name:
          type: string
          description: Anzeigename des Index
          example: ENWEX Solar DE
        energy_source:
          type: string
          description: Energieträger, dessen prognostizierte Erzeugung der Index abbildet
          enum:
            - solar
            - wind
          example: solar
        provider:
          type: string
          description: Herausgeber des Index
          example: Enwex GmbH
        resolution:
          type: string
          description: Zeitliche Auflösung der Indexwerte
          enum:
            - hourly
          example: hourly
        unit:
          type: string
          description: "Einheit der Indexwerte: Prozent der Nennleistung, zwei Nachkommastellen. Ein Wert von 62,50 in einer Stunde bedeutet, dass eine Anlage mit 1 MW Nennleistung in dieser Stunde 0,625 MWh erzeugt."
          enum:
            - percent_of_nominal_power
          example: percent_of_nominal_power
        publication_time:
          type: string
          description: Tägliche lokale Veröffentlichungszeit (Europe/Berlin). Der Index eines Liefertags wird zu dieser Zeit am Vortag veröffentlicht.
          example: "10:00"
      required:
        - id
        - name
        - energy_source
        - provider
        - resolution
        - unit
        - publication_time
    IndexList:
      type: object
      properties:
        indexes:
          type: array
          description: Liste der Indexe
          items:
            $ref: "#/components/schemas/Index"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - indexes
        - pagination
    IndexValue:
      type: object
      description: Der Indexwert einer Lieferstunde
      properties:
        hour:
          type: integer
          description: "Lieferstunde in der EPEX-Zählung (1–24): Stunde 14 ist 13:00–14:00 Uhr Ortszeit (Europe/Berlin). Am 25-Stunden-Tag der Umstellung auf Winterzeit tritt Stunde 3 zweimal auf (3A/3B) — die beiden Einträge unterscheiden sich durch ihre UTC-Zeitstempel; am 23-Stunden-Tag der Umstellung auf Sommerzeit entfällt Stunde 3."
          minimum: 1
          maximum: 24
          example: 14
        delivery_start:
          type: string
          format: date-time
          description: ISO-8601-Beginn der Lieferstunde (UTC)
          example: "2026-07-15T11:00:00Z"
        delivery_end:
          type: string
          format: date-time
          description: ISO-8601-Ende der Lieferstunde (UTC)
          example: "2026-07-15T12:00:00Z"
        value:
          type: number
          description: Indexwert in Prozent der Nennleistung (zwei Nachkommastellen). Vertragsleistung in MW × Wert / 100 ergibt die Liefermenge der Stunde in MWh.
          example: 62.50
      required:
        - hour
        - delivery_start
        - delivery_end
        - value
    IndexDay:
      type: object
      description: Die stündlichen Indexwerte eines Liefertags
      properties:
        index_id:
          type: string
          description: Kennung des Index
          example: enwex-solar-de
        delivery_date:
          type: string
          format: date
          description: Liefertag (`YYYY-MM-DD`)
          example: "2026-07-15"
        published_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Veröffentlichung (UTC) — 10:00 Uhr Europe/Berlin des Vortages
          example: "2026-07-14T08:00:00Z"
        values:
          type: array
          description: Ein Eintrag je Lieferstunde (24; 23 am Tag der Umstellung auf Sommerzeit, 25 am Tag der Umstellung auf Winterzeit)
          items:
            $ref: "#/components/schemas/IndexValue"
      required:
        - index_id
        - delivery_date
        - published_at
        - values
    DayScheduleSlot:
      type: object
      description: Eine Viertelstunde des Tagesfahrplan-Profils
      properties:
        quarter_hour:
          type: integer
          description: "Nummer der Viertelstunde innerhalb des Liefertags (1–96). Am 23-Stunden-Tag der Umstellung auf Sommerzeit entfallen die Viertelstunden der ausgelassenen Stunde 3 — die Nummern 9–12 kommen nicht vor (92 Einträge). Am 25-Stunden-Tag der Umstellung auf Winterzeit treten die Viertelstunden der wiederholten Stunde 3 zweimal auf: Der erste Durchlauf behält die Nummern 9–12, der zweite trägt die Nummern 97–100 (97–100 entsprechen `9b`–`12b` in den Nominierungsdateien); die beiden Durchläufe unterscheiden sich durch ihre UTC-Zeitstempel."
          minimum: 1
          maximum: 100
          example: 53
        delivery_start:
          type: string
          format: date-time
          description: ISO-8601-Beginn der Viertelstunde (UTC)
          example: "2026-07-15T11:00:00Z"
        delivery_end:
          type: string
          format: date-time
          description: ISO-8601-Ende der Viertelstunde (UTC)
          example: "2026-07-15T11:15:00Z"
        value:
          type: number
          description: Indexwert in Prozent der Nennleistung (zwei Nachkommastellen). Alle vier Viertelstunden einer Stunde tragen den Wert dieser Stunde — Vertragsleistung in MW × Wert / 100 ergibt die Fahrplanleistung in MW; die Energie je Viertelstunde ist ein Viertel davon.
          example: 62.50
      required:
        - quarter_hour
        - delivery_start
        - delivery_end
        - value
    DaySchedule:
      type: object
      description: Das Viertelstundenprofil des Index für einen Liefertag. Es ist mit der Veröffentlichung des Index vollständig bestimmt — jede Viertelstunde trägt den Indexwert ihrer Stunde — und ab 10:00 Uhr (Europe/Berlin) des Vortages verfügbar. Die Tagesfahrpläne, die OES daraus berechnet (Transaktionen je Vertrag, Nominierungen je Bilanzkreis), sind versioniert und werden gesondert archiviert; sie sind über die BRP Connect API verfügbar.
      properties:
        index_id:
          type: string
          description: Kennung des Index
          example: enwex-solar-de
        delivery_date:
          type: string
          format: date
          description: Liefertag (`YYYY-MM-DD`)
          example: "2026-07-15"
        published_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Indexveröffentlichung (UTC) — 10:00 Uhr Europe/Berlin des Vortages
          example: "2026-07-14T08:00:00Z"
        slots:
          type: array
          description: Ein Eintrag je Viertelstunde (96; 92 am Tag der Umstellung auf Sommerzeit, 100 am Tag der Umstellung auf Winterzeit)
          items:
            $ref: "#/components/schemas/DayScheduleSlot"
      required:
        - index_id
        - delivery_date
        - published_at
        - slots
    ForecastMonth:
      type: object
      description: Die Langfristprognose des Index für einen Kalendermonat
      properties:
        month:
          type: string
          description: Kalendermonat (`YYYY-MM`)
          example: "2026-07"
        energy_per_mw:
          type: number
          description: Erwartete Energie in MWh je MW Nennleistung (drei Nachkommastellen) — die über den Monat aufsummierte stündliche Langfristprognose des Index. Vertragsleistung in MW × dieser Wert ergibt die erwartete Monatsmenge in MWh.
          example: 158.000
      required:
        - month
        - energy_per_mw
    LongTermForecast:
      type: object
      description: Die monatliche Langfristprognose eines Index. Alle Werte sind Näherungen — maßgeblich für die Lieferung ist der je Liefertag veröffentlichte Index, nicht die Langfristprognose.
      properties:
        index_id:
          type: string
          description: Kennung des Index
          example: enwex-solar-de
        as_of:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel (UTC) des Prognoselaufs, auf dem diese Antwort beruht
          example: "2026-06-30T08:00:00Z"
        months:
          type: array
          description: Ein Eintrag je Kalendermonat, vom laufenden Monat bis zum Dezember des Folgejahres (sofern nicht durch `from_month`/`to_month` eingegrenzt)
          items:
            $ref: "#/components/schemas/ForecastMonth"
      required:
        - index_id
        - as_of
        - months
  responses:
    NotFound:
      description: Die Ressource existiert nicht, ist noch nicht veröffentlicht, oder der Aufrufer hat keinen Zugriff
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/delivery_day_not_published
            title: Liefertag nicht veröffentlicht
            status: 404
            detail: No day schedule has been published for 2026-07-16 yet. The index for a delivery day is published at 10:00 (Europe/Berlin) on the preceding day.
            instance: /v1/indexes/enwex-solar-de/day-schedule
    BadRequest:
      description: Ungültige Anfrage — Validierungsfehler oder Verstoß gegen eine Geschäftsregel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/validation
            title: Validierung fehlgeschlagen
            status: 400
            instance: /v1/indexes/enwex-solar-de/values
            errors:
              - field: delivery_date
                code: invalid_format
                message: "Invalid date. Expected YYYY-MM-DD, received '15.07.2026'"
    Unauthorized:
      description: Fehlender oder ungültiger API-Schlüssel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/invalid_api_key
            title: Ungültiger API-Schlüssel
            status: 401
    Forbidden:
      description: Dem API-Schlüssel fehlen die erforderlichen Scopes
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/insufficient_scopes
            title: Unzureichende Scopes des API-Schlüssels
            status: 403
            detail: "Missing scope: forecasts:read. Please create a new API key with the required scopes."
paths:
  /v1/indexes:
    get:
      operationId: listIndexes
      summary: Indexe auflisten
      description: "Die ENWEX-Referenzindexe auflisten. Es gibt zwei Indexe: ENWEX Solar DE und ENWEX Wind DE — die Referenzindexe der indexbasierten Lieferung, veröffentlicht von der Enwex GmbH und von OES unter Lizenz bereitgestellt. Jeder Index bildet die prognostizierte Erzeugung der in Deutschland installierten Solar- oder Windleistung ab, stündlich aufgelöst und in Prozent der Nennleistung ausgedrückt. Die Indexdaten werden zur Vertragsabwicklung bereitgestellt; eine Verwendung darüber hinaus ist nicht gestattet.\n\nErforderlicher Scope: `forecasts:read`"
      tags:
        - Indexes
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - forecasts:read
      parameters:
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Indexe
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndexList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/indexes/{index_id}:
    get:
      operationId: getIndex
      summary: Index abrufen
      description: "Einen einzelnen Index über seine Kennung abrufen, samt Auflösung, Einheit und täglicher Veröffentlichungszeit.\n\nErforderlicher Scope: `forecasts:read`"
      tags:
        - Indexes
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - forecasts:read
      parameters:
        - $ref: "#/components/parameters/IndexIdParam"
      responses:
        "200":
          description: Angaben zum Index
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Index"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/indexes/{index_id}/values:
    get:
      operationId: listIndexValues
      summary: Indexwerte auflisten
      description: "Die stündlichen Indexwerte eines Liefertags, in Prozent der Nennleistung (zwei Nachkommastellen). Enwex veröffentlicht den Index täglich um 10:00 Uhr (Europe/Berlin) für den folgenden Liefertag; vor 10:00 Uhr ist der Index des laufenden Tages der zuletzt verfügbare. Ohne `delivery_date` wird der zuletzt veröffentlichte Liefertag geliefert.\n\nEine Anlage mit 1 MW Nennleistung erzeugt in der Stunde Wert / 100 MWh; die Liefermenge eines indexbasierten Vertrags ergibt sich als Vertragsleistung in MW × Wert / 100.\n\nErforderlicher Scope: `forecasts:read`"
      tags:
        - Index values
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - forecasts:read
      parameters:
        - $ref: "#/components/parameters/IndexIdParam"
        - $ref: "#/components/parameters/DeliveryDateParam"
      responses:
        "200":
          description: Die stündlichen Indexwerte des Liefertags
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndexDay"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/indexes/{index_id}/day-schedule:
    get:
      operationId: getDaySchedule
      summary: Tagesfahrplan abrufen
      description: "Das Viertelstundenprofil des Index für einen Liefertag. Jede der vier Viertelstunden einer Stunde trägt den Indexwert dieser Stunde; Vertragsleistung in MW × Wert / 100 ergibt die Fahrplanleistung in MW, und die Energie je Viertelstunde ist ein Viertel der Stundenenergie. Das Profil ist mit der Veröffentlichung des Index vollständig bestimmt und ab 10:00 Uhr (Europe/Berlin) des Vortages verfügbar. Ohne `delivery_date` wird der zuletzt veröffentlichte Liefertag geliefert: ab 10:00 Uhr (Europe/Berlin) der Folgetag, davor der laufende Tag.\n\nAus diesem Profil berechnet OES die Tagesfahrpläne — Transaktionen je Vertrag, Nominierungen je Bilanzkreis — und stellt sie um 12:00 Uhr (Europe/Berlin) des Vortages bereit; diese Fahrpläne sind versioniert und über die BRP Connect API verfügbar.\n\nErforderlicher Scope: `forecasts:read`"
      tags:
        - Day schedule
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - forecasts:read
      parameters:
        - $ref: "#/components/parameters/IndexIdParam"
        - $ref: "#/components/parameters/DeliveryDateParam"
      responses:
        "200":
          description: Das Viertelstundenprofil des Liefertags
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DaySchedule"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/indexes/{index_id}/long-term-forecast:
    get:
      operationId: listLongTermForecast
      summary: Langfristprognose auflisten
      description: "Die monatliche Langfristprognose des Index, vom laufenden Monat bis zum Dezember des Folgejahres. Jeder Monat trägt die zur Energie aufsummierte stündliche Langfristprognose in MWh je MW Nennleistung — Vertragsleistung in MW × dieser Wert ergibt die erwartete Monatsmenge, die Grundlage der Bilanzkreis-Prognose in BRP Connect.\n\nAlle Werte sind Näherungen: Maßgeblich für die Lieferung ist der je Liefertag veröffentlichte Index, nicht die Langfristprognose.\n\nErforderlicher Scope: `forecasts:read`"
      tags:
        - Long-term forecast
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - forecasts:read
      parameters:
        - $ref: "#/components/parameters/IndexIdParam"
        - $ref: "#/components/parameters/FromMonthParam"
        - $ref: "#/components/parameters/ToMonthParam"
      responses:
        "200":
          description: Monatliche Langfristprognose
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LongTermForecast"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
