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

Jede Antwort enthält:

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 Plan-Kontingent steht im Weg — heute betrifft das nur das Anlegen von Kategorien.

• 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.

• 409

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

Fehlerformen

Jeder Fehler kommt in derselben Form zurück — statusCode, message und ein errors-Objekt, das benennt, was falsch war. Ein fehlender oder ungültiger Schlüssel kann auch ganz ohne Body zurückkommen.

{
  "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, und dein Tarif kann weiterhin älteren Verlauf ausblenden. Nichts davon ist ein Rate Limit — siehe unten.

• Konten, Kontostand, Übersicht, Kategorien, 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 Plan, 365 in einem bezahlten. Es gibt keine Option, die nie abläuft.

• Dein Plan 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.

• Pläne nennen auch ein API-Anfrage-Kontingent — 500 im kostenlosen Plan, mehr in jedem bezahlten.

Was hier fehlt: Es gibt heute keine Drosselung pro Anfrage auf REST, keinen 429, und keine Rate-Limit-Header — ein gestohlener Schlüssel wird also von nichts auf unserer Seite gebremst. Wenn du dir bei einem Schlüssel je unsicher bist, widerrufe ihn: das kappt ihn sofort (siehe Sicherheit und Schlüsselverwaltung oben). Und nimm, weil diese API in der Beta ist, nicht an, dass das so bleibt.

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.

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"
  }
}