Für Entwickler

Elpia ist ein Kern, mit dem viele Apps sprechen: eine Webseite, eine Minecraft-Mod, ein Server-Plugin, eine Fokus-App und was noch kommt. Alles, was sie nutzen, steht hier, und alles Öffentliche ist ohne Konto lesbar.

Womit du sprechen kannst

  • REST-API

    JSON über HTTPS, versioniert unter /v1. Dieselben Pfade von der Webseite, von einem Gerät und aus einem Skript.

    Zur Referenz

  • OpenAPI-Dokument

    Dieselben Endpunkte maschinenlesbar, um einen Client zu erzeugen oder sie in ein HTTP-Werkzeug zu laden.

    openapi.json

  • llms.txt

    Ein kurzer Überblick für KI-Agenten, in dem Format, nach dem sie zuerst schauen.

    llms.txt

Wie du dich ausweist

Bei jedem Endpunkt steht, was er davon braucht. Ein Gerät bekommt nie eine Login-Sitzung: Sein Schlüssel darf Aktivitäten melden und sonst nichts.

Offen (21)
Kein Login. Regeln, Budget, Katalog, Deeds, Belege und Statistik sind öffentlich – genau darum geht es.
Mensch (18)
Das Sitzungs-Cookie der Webseite oder ein Authorization-Header mit dem Sitzungstoken für Aufrufer ohne Cookies. Beim Anmelden kommt dieses Token im Header set-auth-token zurück.
App oder Gerät (3)
Ein Authorization-Header mit dem API-Schlüssel eines Geräts, das du bestätigt hast. Mit Ed25519-Signatur zählt die gemeldete Aktivität als verifiziert statt nur als Gerätemeldung.
Inhaber (20)
Ein angemeldeter Mensch mit Admin-Rolle. Alles, was Regeln, Preise oder Geld ändert, steht hier.

Hausregeln

  • Fehler sehen überall gleich aus

    Ein Fehler trägt einen Fehlercode und eine Nachricht, eine fehlgeschlagene Prüfung zusätzlich die Issues. Unerwartete Fehler tragen nur eine Request-Id; die Details bleiben in unserem Log statt in deiner Antwort.

  • Jede Anfrage hat eine Id

    Schick X-Request-Id mit, dann wird sie genutzt und zurückgegeben; sonst bekommst du eine. Nenne sie, wenn etwas schiefging, dann ist es im Log auffindbar.

  • Limits gelten pro Konto, nicht pro Adresse

    Eine Adresse kann ein ganzer Haushalt sein, ein Konto viele Adressen. Über dem Limit kommt 429 mit Retry-After; die Antwort verrät nie, um welches Konto es ging.

  • Wiederholen ist sicher

    Eine Aktivität mit derselben externalId wird einmal gespeichert. Nach einem Timeout einfach erneut schicken, statt zu raten, ob sie ankam.

  • Nichts wird überschrieben

    Regeln, Preise, Buchungen, Auszahlungen und Prüfeinträge sind append-only. Eine Korrektur ist ein neuer Eintrag, der sagt, was sich geändert hat und warum.

  • Standorte bleiben grob

    Aktivitäten tragen höchstens ein Land oder eine Stromzone. Es gibt keinen Endpunkt für etwas Genaueres, weil es nichts Genaueres gibt.

Geplant

  • MCP-Server

    Eine dünne Schicht über denselben REST-Endpunkten, damit ein KI-Agent den Katalog nachschlagen, Deeds lesen und Statistik prüfen kann. Kommt, sobald die öffentliche API stabil ist und Schlüssel Scopes tragen: Ein Agent soll lesen können, ohne einen Schlüssel zu halten, der auch Drops ausgeben darf.

  • Webhooks

    Ein signierter Aufruf bei dir, wenn aus einer Einlösung eine Deed wird, statt uns immer wieder zu fragen.

  • Mit Elpia anmelden

    Elpia als OIDC-Anbieter, damit eine verbundene App keine eigenen Passwörter halten muss.

Zur Referenz