Era-API

Schnellstart

Bevor du loslegst, brauchst du ein Era-Konto mit mindestens einer verbundenen Bank — ohne Verbindung haben diese Endpunkte nichts zurückzugeben.

1. 1

   Melde dich bei Era an und verbinde eine Bank, falls noch nicht geschehen.

2. 2

   Öffne deine API-Schlüssel im Dashboard und erstell einen. Alle Scopes sind vorab angehakt, also hak die ab, die du nicht brauchst — für diese Endpunkte bleibt banking:read übrig. Du wählst außerdem eine Gültigkeitsdauer; eine Option „läuft nie ab“ gibt es nicht.

3. 3

   Kopier den Schlüssel. Er wird einmal angezeigt, und wir können ihn nicht erneut zeigen. Kopier ihn und bewahr ihn an einem sicheren Ort auf, zum Beispiel in einem Secrets-Manager. Verlierst du einen Schlüssel, kannst du ihn nicht erneut einsehen. Leg stattdessen einen neuen an.

4. 4

   Schick ihn mit deinem Request im Header mit.

curl "https://forge.era.app/api/banking/transactions?page=1&pageSize=20" \
  -H "X-API-Key: fmk_your_key_here"

{
  "transactions": [ … ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 412,
    "totalPages": 21
  },
  "historyWindowApplied": true,
  "historyWindowFloorDate": "2026-06-28",
  "historyWindowHiddenCount": 137,
  "historyWindowEarliestDate": "2024-03-02",
  "historyWindowDegraded": false
}

Verfügbare APIs

Die Era-API umfasst die folgenden APIs:

• GET/banking/accounts

  Jedes Konto, das du sehen kannst, über alle verbundenen Institute hinweg.

• GET/banking/accounts/{accountId}/balance

  Der Saldo eines Kontos, inklusive Kreditfelder bei einer Verbindlichkeit.

• GET/banking/accounts/summary

  Summen über alle Konten, die du sehen kannst.

• GET/banking/transactions

  Deine Transaktionen, seitenweise.

• PUT/banking/transactions/{id}

  Eine Transaktion ändern

• PUT/banking/transactions/bulk

  Bis zu 100 auf einmal ändern

• GET/banking/categories

  Die gesamte Kategorie-Taxonomie, mit verschachtelten Unterkategorien.

• POST/banking/categories

  Eine Kategorie anlegen

• GET/banking/tags

  Alle Tags deines Kontos, in einer Antwort.

• POST/banking/tags

  Einen Tag anlegen

Authentifizierung

Sende deinen Schlüssel auf eine von zwei Arten:

Jeder Request ist TLS-verschlüsselt.

Schlüssel laufen ab, und du wählst beim Erstellen, wie bald. Das Maximum sind 90 Tage im kostenlosen Tarif und 365 in einem bezahlten — eine Option „läuft nie ab“ existiert nicht, also braucht alles, was du darauf baust, einen Plan zum Rotieren des Schlüssels, bevor er verfällt.

Antwort-Header

Eine Request-ID kommt bei jeder Antwort zurück. Die Rate-Limit-Header kommen bei den Aufrufen zurück, die Era gemessen hat. Wenn Era deine Nutzung nicht messen kann, wird der Aufruf bedient und es geht keiner von ihnen raus.

Fehler

Die API liefert diese Fehler-Statuscodes:

• 400

  Fehlerhafte Eingabe: ein falscher Parameter, ein leeres oder über 100 Einträge großes Bulk-Update, oder ein Schreibzugriff, der dasselbe Feld im selben Aufruf setzt und löscht.

• 401

  Kein Schlüssel, oder einer, der sich nicht parsen lässt. Sende ihn als X-API-Key-Header oder als Bearer-Token.

• 402

  Ein Tarifkontingent steht im Weg — heute betrifft das nur das Anlegen von Kategorien. Es geht darum, was du anlegst, nicht wie schnell du aufrufst: Warten löst es nicht, ein größerer Tarif schon. Zu schnelles Aufrufen ist dagegen ein 429.

• 403

  Der Schlüssel trägt nicht den Scope, den dieser Aufruf braucht — oder, bei einem der beiden Transaktions-Schreibzugriffe, die ID gehört jemand anderem oder existiert gar nicht. Die API unterscheidet die beiden Fälle nicht.

• 404

  Ein Konto, das es nicht gibt. Nur der Kontostand-Endpunkt gibt das zurück: ein accountGroupKey, der kein Konto benennt, oder einer, der gar nicht wie ein Schlüssel aussieht, kommt als 404 ohne Body zurück. Transaktionen liefern nie 404 — siehe 403.

• 409

  Etwas anderes hat die Zeile geändert, während du geschrieben hast. Lies sie erneut und schreibe erneut.

• 429

  Zu viele Anfragen. Du hast dein Tagesbudget aufgebraucht oder die Minuten-Burst-Grenze erreicht. Retry-After sagt, wie lange du warten musst, und anders als bei einem 402 löst Warten das. Unter Limits steht, welche Grenze abgelehnt hat, und die Zahlen pro Tarif.

Fehlerformen

Die meisten Fehler kommen in derselben Form zurück — statusCode, message und ein errors-Objekt, das benennt, was falsch war. Nicht alle: Ein 401 und ein 404 kommen ganz ohne Body zurück, lies also den Status, bevor du den Body liest.

{
  "statusCode": 403,
  "message": "One or more errors occurred!",
  "errors": {
    "generalErrors": ["Transaction does not belong to the authenticated user"]
  }
}

Request-ID

Jede Antwort trägt einen fly-request-id-Header. Gib ihn an, wenn du den Support zu einer bestimmten Anfrage kontaktierst.

# Print the response headers, including fly-request-id; discard the body
curl -sS -D - -o /dev/null "https://forge.era.app/api/banking/transactions?page=1&pageSize=20" \
  -H "X-API-Key: fmk_your_key_here"

# A write call: same header, plus a JSON body
curl -sS -D - -X PUT "https://forge.era.app/api/banking/transactions/utgr_your_transaction_id" \
  -H "X-API-Key: fmk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"categoryKey": "fcat_dining", "merchantName": "Corner Cafe"}'

Häufige Fehler

• Ein Feld im selben Schreibzugriff setzen und löschen — 400.

• Mehr als 100 IDs in einem Bulk-Update — 400, und nichts wird geändert. Weniger als eine ID ist genauso.

• Eine Transaktion, die nicht dir gehört oder gar nicht existiert — 403, niemals 404. Die Antwort verrät also nie, ob eine ID überhaupt existiert, nur dass sie nicht dir gehört.

• Etwas anderes hat die Zeile zuerst geändert — 409.

Limits

Zwei der zehn dokumentierten Endpunkte begrenzen, wie viel du in einem Aufruf anfordern kannst. Die anderen acht nicht.

Das heißt nicht unbegrenzt: Schlüssel laufen weiterhin ab, Schreibvorgänge haben weiterhin Feldlängenbegrenzungen, das Anlegen einer Kategorie kann an ein Tarifkontingent stoßen, und dein Tarif kann weiterhin älteren Verlauf ausblenden. Nichts davon ist ein Rate Limit — siehe unten.

• Konten, Kontostand, Übersicht, die Kategorie- und Tag-Listen, das Anlegen einer Kategorie, das Anlegen eines Tags und das Schreiben einzelner Transaktionen haben kein Volumenlimit pro Aufruf. Du bekommst entweder die gesamte Menge zurück oder genau die eine Zeile, die du benannt hast.

• pageSize wird auf 100 gekappt, nicht abgelehnt. Fordere mehr an, und du bekommst 100 Zeilen mit einem 200 zurück — lies pagination.pageSize aus der Antwort, statt dem zu vertrauen, was du gesendet hast.

• Der Bulk-Schreibzugriff für Transaktionen ist auf 100 IDs gedeckelt, und anders als pageSize wird er abgelehnt statt gekappt: Sende 101, und du bekommst einen 400, und nichts ändert sich.

• Schlüssel laufen nach einem Zeitplan ab, den du bei der Erstellung wählst — bis zu 90 Tage im kostenlosen Tarif, 365 in einem bezahlten. Es gibt keine Option, die nie abläuft.

• Dein Tarif kann eine Verlaufsfenster-Untergrenze setzen, die ältere Transaktionen verbirgt. Die Transaktions-Antwort trägt die historyWindow-Felder, die dir sagen, ob eine galt und wo sie lag.

Rate-Limits

Jeder Tarif darf diese API aufrufen, und jeder Tarif wird gemessen. Gezählt werden die Aufrufe, die du mit einem Schlüssel machst. Zwei Grenzen gelten gleichzeitig — ein Tagesbudget und eine Minuten-Burst-Grenze — und wer eine davon überschreitet, bekommt einen 429.

Dein Tagesbudget gehört dir, nicht einem Schlüssel. Jeder REST-Schlüssel in deinem Konto zieht vom selben Tagesbudget ab, ein zweiter Schlüssel kauft dir also keine zusätzlichen Aufrufe. MCP-Tool-Aufrufe werden getrennt gezählt: das eine zu verbrauchen verbraucht nie das andere.

Wenn Era einen Aufruf misst, trägt die Antwort X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Alle drei beschreiben dein Tagesbudget, das über 24 Stunden rollt, statt um Mitternacht zurückgesetzt zu werden: Anfragen kommen einzeln zurück, sobald deine ältesten Aufrufe 24 Stunden alt werden. Die Minuten-Burst-Grenze hat keinen Header, also richte dein Tempo selbst nach dem Wert in der Tabelle. Remaining kann deutlich über null stehen, während ein Burst trotzdem mit 429 zurückkommt. Wenn Era deine Nutzung nicht messen kann, wird der Aufruf bedient und es gehen keine Rate-Limit-Header raus — behandle fehlende Header also als fehlenden Messwert, nicht als Fehler.

Was ein 429 dir sagt

Ein Problem-Details-Body. Sein detail-Feld ist Klartext, keine strukturierten Felder: Es nennt die Grenze, an die du gestoßen bist, was diese Grenze erlaubt, wann deine nächste Anfrage frei wird, und den Tarif, der sie anhebt, oder dass du schon im höchsten bist. Parse es nicht. Um im Code zu verzweigen, lies die Header: Remaining bei 0 heißt, das Tagesbudget hat abgelehnt, über 0 heißt, es war die Minuten-Burst-Grenze.

{
  "type": "https://httpstatuses.com/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You've used up your daily budget of 250 requests. Your next request frees up at 2026-09-16T09:00:00Z. The Organize plan raises it."
}

Ein 429 trägt außerdem Retry-After, eine ganze Zahl an Sekunden, gemessen an der Grenze, die abgelehnt hat: bis zu einer Minute bei der Minuten-Burst-Grenze, bis zu 24 Stunden beim Tagesbudget. Ein abgelehnter Aufruf verbraucht nichts, zu frühes Wiederholen kostet dich also nichts, kommt aber wieder mit 429 zurück. Wenn Retry-After abgelaufen ist, wird eine Anfrage frei, nicht das ganze Budget. Schick sie, und lies dann die Header oder das nächste Retry-After.

Nichts davon schützt einen Schlüssel, den du aus den Augen verloren hast. Ein geleakter Schlüssel verbraucht dein Budget genau so, wie du es tätest. Wenn du dir bei einem unsicher bist, widerrufe ihn. Siehe Sicherheit und Schlüsselverwaltung weiter unten.

Konventionen

Antwortfelder sind camelCase. Bei Query-Parametern spielt die Groß- und Kleinschreibung keine Rolle, camelCase funktioniert dort also ebenfalls — die veröffentlichte Spezifikation schreibt sie PascalCase, deshalb begegnen dir beide Formen.

Ein Feld, das einen Kalendertag nennt, ist YYYY-MM-DD. Ein Feld, das einen Zeitpunkt nennt, ist ISO 8601 mit Zeitzonenversatz.

Seitengrößen werden gekappt, nicht abgelehnt. Frag ein pageSize von 500 an, und du bekommst 100 Zeilen und ein 200, keinen Fehler — lies pagination.pageSize also aus der Antwort zurück, statt dich auf das zu verlassen, was du geschickt hast.

Eine Antwort kann Felder tragen, die diese Seite nicht aufführt. Ignorier die, die du nicht kennst, statt daran zu scheitern — das hält deinen Client am Laufen, während die API wächst.

REST ist schlichtes HTTP, für den Aufruf braucht es also kein SDK — jede Sprache mit einem HTTP-Client reicht aus. Es gibt nichts zu installieren.

Versionierung und Änderungen

Alles, was hier dokumentiert ist, fällt unter diese Richtlinie.

Es gibt keine Versionsnummer im Pfad und keinen Versions-Header. Jeder Endpunkt hat eine aktive Version, und das ist die hier dokumentierte.

Was wir ohne Ankündigung ändern dürfen

Nichts davon bricht einen Client, der sich an die Konventionen oben hält.

• Einen Endpunkt hinzufügen, oder eine Operation auf einem bestehenden.

• Ein Feld zu einer Antwort hinzufügen.

• Einen optionalen Parameter hinzufügen. Lass ihn weg, und nichts ändert sich.

• Einen Wert zu einer festen Auswahl hinzufügen, etwa einen Status oder einen Typ.

• Einen Antwort-Header hinzufügen.

Was wir nicht ohne Ankündigung ändern

Jedes davon kann einen laufenden Client brechen.

• Einen Endpunkt entfernen, oder seinen Pfad oder seine Methode ändern.

• Ein Antwortfeld entfernen oder umbenennen.

• Den Typ eines Feldes oder seine Bedeutung ändern.

• Einen heute optionalen Parameter zur Pflicht machen.

• Eingaben ablehnen, die heute akzeptiert werden.

• Den Scope ändern, den ein Endpunkt braucht.

Vor jeder dieser Änderungen steht es mindestens 90 Tage vorher im Changelog, zusammen mit dem, was du anpassen musst. Was heute funktioniert, funktioniert bis dahin weiter.

Änderungen werden im Changelog angekündigt, verlinkt im Abschnitt „Changelog“ unten. E-Mail oder Feed gibt es noch nicht, schau also dort nach, wenn du Arbeit gegen die API planst.

Solange die API in der Beta ist, wächst der dokumentierte Umfang weiter. Was schon hier steht, bricht dir nichts ohne Vorwarnung.

Changelog

Neuerungen der Era Developer Platform, einschließlich der Era API, neueste zuerst. Die Richtlinie oben sagt, was vorgewarnt wird und wie lange; im Changelog stehen diese Vorwarnungen.

Sicherheit und Schlüsselverwaltung

Konten

{
  "accounts": [
    {
      "accountGroupKey": "uagr_7f3c9a21",
      "connectionId": "ucon_4b19e02c",
      "name": "Everyday Checking",
      "currentBalance": 4820.16,
      "supportsTransactions": true,
      …
    }
  ],
  "excludedAccountCount": 1
}

Kontosaldo

{
  "accountGroupKey": "uagr_7f3c9a21",
  "currentBalance": 4820.16,
  "availableBalance": 4712.03,
  "creditLimit": null,
  "currencyCode": "USD",
  "availableCredit": null,
  "asOf": "2026-08-11T09:32:00Z",
  "visibility": null
}

Kontoübersicht

{
  "userId": "7d1c0b93a8e24f60",
  "accounts": [ … ],
  "totalVisibleCount": 6,
  "totalHiddenCount": 2,
  "totalAssets": 48210.75,
  "totalLiabilities": 9327.40,
  "netWorthHint": 38883.35,
  "computedAt": "2026-08-11T09:32:00Z"
}

Transaktionen

{
  "transactions": [ … ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 412,
    "totalPages": 21
  },
  "historyWindowApplied": true,
  "historyWindowFloorDate": "2026-06-28",
  "historyWindowHiddenCount": 137,
  "historyWindowEarliestDate": "2024-03-02",
  "historyWindowDegraded": false
}

{
  "transaction": { … }
}

{
  "transactions": [ … ]
}

Kategorien

{
  "packs": [
    {
      "packSlug": "default",
      "packName": "Era default categories",
      "isDefault": true,
      "categories": [
        {
          "projectionKey": "fcat_food_dining",
          "categoryName": "Food & dining",
          "isTopLevel": true,
          "children": [ … ]
        }
      ]
    }
  ],
  "meterLimit": 25,
  "canCreateCustomCategories": true
}

{
  "categoryKey": "fcat_side_hustle_9f2a",
  "overlayProjectionKey": "fcov_9f2a1c",
  "action": "created",
  "isQuotaExceeded": false,
  "createdMappingRuleKeys": [ … ],
  …
}

Tags

{
  "tags": [
    {
      "tagKey": "utag_9c2f01ab",
      "name": "business-expense",
      "displayName": "Business expense",
      "tagType": "user",
      "color": "#6DC6BA",
      "transactionCount": 42
    }
  ]
}

{
  "tag": {
    "tagKey": "utag_9c2f01ab",
    "name": "business-expense",
    "displayName": "Business expense",
    "tagType": "user",
    "version": 1,
    "createdAt": "2026-08-26T09:15:00Z"
  }
}