Quickstart

validfrom ist eine GraphQL-API. Es gibt genau einen Endpoint, an den alle Abfragen als POST gehen:

POST https://api.validfrom.dev/graphql

Zum Ausprobieren im Browser gibt es GraphiQL. Dort sind das Schema und alle Beschreibungen direkt durchsuchbar; dieselben Beschreibungen stehen in der Schema-Referenz.

Die erste Abfrage

Welche Bezugsgröße galt am 01.06.2026, nach dem Kenntnisstand vom 01.10.2026?

curl https://api.validfrom.dev/graphql \
-H 'Content-Type: application/json' \
-d '{"query": "{ dataPoint(seriesId: \"de.sv.allgemein.bezugsgroesse\", validOn: \"2026-06-01\", knownOn: \"2026-10-01\") { validFrom knownFrom values { key value } } }"}'

Die Antwort:

{
  "data": {
    "dataPoint": {
      "validFrom": "2026-01-01",
      "knownFrom": "2026-09-14",
      "values": [
        { "key": "jahr", "value": "47460" },
        { "key": "monat", "value": "3955" }
      ]
    }
  }
}

Eine Reihe wie die Bezugsgröße hat mehrere Wertteile, hier Jahres- und Monatswert. Sie werden immer gemeinsam geliefert. Die Einheit steht an der Reihe (series { valueParts { key unit } }), nicht am einzelnen Wert. Wertteile immer über key ansprechen, nie über die Position in der Liste.

Welche Reihen es gibt, liefert availableSeries; sie stehen auch im Katalog.

Zwei Datumsargumente

• validOn – für welchen Tag der Wert gelten soll.
• knownOn – nach welchem Kenntnisstand gefragt wird. Spätere Korrekturen bleiben unberücksichtigt.

Beide Argumente sind optional; fehlen sie, nimmt der Server das heutige Datum. Damit kann sich die Antwort auf dieselbe Abfrage mit der Zeit ändern. Für Abrechnungsläufe, die reproduzierbar bleiben müssen, beide Daten immer explizit mitgeben. Wie die beiden Achsen zusammenspielen, erklärt Konzepte.

Dezimalwerte kommen als String

Beträge haben den Typ Decimal und werden als JSON-String übertragen, zum Beispiel "47460" oder "18.6". So geht beim Parsen keine Genauigkeit verloren. In einen Dezimaltyp mit beliebiger Genauigkeit übernehmen (BigDecimal, decimal.Decimal, …), nicht in double oder float. Dezimaltrennzeichen ist der Punkt, Tausendertrennzeichen gibt es nicht.

null ist kein Fehler

dataPoint liefert null, wenn für die Kombination aus validOn und knownOn kein Wert galt oder bekannt war – etwa weil validOn vor dem Beginn der Reihe (coveredFrom) liegt oder knownOn vor dem Tag, an dem der Wert in den Katalog aufgenommen wurde. Das ist die korrekte Antwort auf die Frage, kein Fehler. Ein unbekannter seriesId liefert ebenfalls null.

Belege abrufen

Zu jedem Wert gehören Rechtsquellen (legalSources) mit Rolle, Fundstelle und Dokument. Document.archiveUrl ist ein dauerhafter Link auf die archivierte Kopie: ohne Anmeldung abrufbar, immer dieselben Bytes, sha256 als ETag. Er kann so, wie er ist, an einen Prüfer weitergegeben werden.

{
dataPoint(seriesId: "de.sv.allgemein.bezugsgroesse", validOn: "2026-06-01", knownOn: "2026-10-01") {
  legalSources {
    role
    provision
    binding
    document { citation title archiveUrl sha256 }
  }
}
}