API Era

Démarrage rapide

Avant de commencer, il te faut un compte Era avec au moins une institution branchée — sans connexion, ces points de terminaison n'ont rien à retourner.

1. 1

   Connecte-toi à Era et branche une institution, si ce n'est pas déjà fait.

2. 2

   Ouvre tes clés d'API dans le tableau de bord et crée une clé. Toutes les portées sont cochées au départ, alors décoche celles dont tu n'as pas besoin : pour ces points de terminaison, il reste banking:read. Tu choisis aussi une expiration ; il n'y a pas d'option « jamais ».

3. 3

   Copie la clé. Elle s'affiche une seule fois, et on ne peut pas la réafficher. Copie-la et conserve-la en lieu sûr, par exemple dans un gestionnaire de secrets. Si tu perds une clé, tu ne peux plus la consulter. Crée-en une nouvelle à la place.

4. 4

   Envoie-la dans un en-tête avec ta requête.

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
}

API disponibles

L'API Era comprend les API suivantes :

• GET/banking/accounts

  Chaque compte que tu peux voir, sur tous tes établissements connectés.

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

  Le solde d'un compte, avec les champs de crédit renseignés s'il s'agit d'un passif.

• GET/banking/accounts/summary

  Les totaux sur tous les comptes que tu peux voir.

• GET/banking/transactions

  Tes transactions, une page à la fois.

• PUT/banking/transactions/{id}

  Modifier une transaction

• PUT/banking/transactions/bulk

  Modifier jusqu'à 100 à la fois

• GET/banking/categories

  Toute la taxonomie des catégories, avec les sous-catégories imbriquées.

• POST/banking/categories

  Ajouter une catégorie

• GET/banking/tags

  Toutes les étiquettes de ton compte, en une seule réponse.

• POST/banking/tags

  Créer une étiquette

Authentification

Envoie ta clé de l'une de ces deux façons :

Chaque requête est chiffrée avec TLS.

Les clés expirent, et tu choisis dans combien de temps à la création. Le maximum est de 90 jours sur le forfait gratuit et de 365 sur un forfait payant — il n'existe pas d'option « n'expire jamais », alors ce que tu bâtis là-dessus a besoin d'un plan pour faire tourner la clé avant qu'elle tombe.

En-têtes de réponse

Chaque réponse inclut :

Erreurs

L'API renvoie ces codes de statut d'erreur :

• 400

  Entrée invalide : un paramètre incorrect, une mise à jour groupée vide ou de plus de 100 éléments, ou une écriture qui définit et efface le même champ dans le même appel.

• 401

  Pas de clé, ou une clé qui ne s'analyse pas. Envoie-la dans l'en-tête X-API-Key ou comme jeton bearer.

• 402

  Un quota du forfait fait obstacle — aujourd'hui, cela ne concerne que la création de catégories.

• 403

  La clé ne porte pas la portée dont cet appel a besoin — ou, sur l'une des deux écritures de transactions, l'id appartient à quelqu'un d'autre ou n'existe pas. L'API ne distingue pas ces deux cas.

• 409

  Autre chose a modifié la ligne pendant que tu écrivais. Relis-la et renvoie ton écriture.

Formes d'erreur

Chaque erreur revient sous la même forme : statusCode, message et un objet errors qui nomme ce qui n'allait pas. Une clé absente ou invalide peut revenir sans corps du tout.

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

ID de requête

Chaque réponse porte un en-tête fly-request-id. Indique-le quand tu contactes le support à propos d'une requête précise.

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

Erreurs courantes

• Définir un champ et l'effacer dans la même écriture — 400.

• Plus de 100 id dans une mise à jour groupée — 400, et rien n'est modifié. Moins d'un id donne le même résultat.

• Une transaction qui n'est pas la tienne, ou qui n'existe pas — 403, jamais 404. La réponse ne te dit donc jamais si un id existe, seulement qu'il n'est pas à toi.

• Autre chose a modifié la ligne en premier — 409.

Limites

Deux des dix endpoints documentés plafonnent ce que tu peux demander en un seul appel. Les huit autres non.

Ça ne veut pas dire illimité : les clés expirent toujours, les écritures ont toujours des limites de longueur de champ, et ton forfait peut toujours masquer l'historique ancien. Rien de tout ça n'est une limite de débit — voir plus bas.

• Comptes, solde, résumé, catégories, tags et l'écriture d'une seule transaction n'ont aucun plafond de volume par appel. Tu reçois l'ensemble au complet, ou la seule ligne que tu as nommée.

• pageSize est plafonné à 100, jamais refusé. Demande-en plus et tu reçois 100 lignes avec un 200 — lis pagination.pageSize dans la réponse plutôt que de faire confiance à ce que tu as envoyé.

• L'écriture groupée de transactions est plafonnée à 100 id, et contrairement à pageSize elle est refusée plutôt que plafonnée : envoie 101 et tu reçois un 400, rien ne change.

• Les clés expirent selon un calendrier que tu choisis à la création — jusqu'à 90 jours sur le forfait gratuit, 365 sur un forfait payant. Il n'existe pas d'option sans expiration.

• Ton forfait peut appliquer un plancher de fenêtre d'historique qui masque les transactions plus anciennes. La réponse des transactions porte les champs historyWindow qui indiquent si un plancher s'est appliqué et où il se situe.

• Les forfaits indiquent aussi une allocation de requêtes API — 500 sur le forfait gratuit, plus sur chaque forfait payant.

Ce qui n'existe pas : aucune limitation par requête sur REST aujourd'hui, pas de 429, pas d'en-têtes de limite de débit — une clé qui a fuité n'est donc ralentie par rien de notre côté. Si tu as un doute sur une clé, révoque-la : cela la coupe immédiatement (voir Sécurité et gestion des clés plus haut). Et, cette API étant en bêta, ne présume pas que cela restera vrai.

Conventions

Les champs de réponse sont en camelCase. Les paramètres de requête, eux, ne sont pas sensibles à la casse, alors le camelCase marche là aussi — la spec publiée les écrit en PascalCase, c'est pour ça que tu verras les deux formes circuler.

Un champ qui nomme un jour de calendrier est en YYYY-MM-DD. Un champ qui nomme un instant précis est en ISO 8601 avec un décalage horaire.

Les tailles de page sont ramenées dans les bornes, pas refusées. Demande un pageSize de 500 et tu obtiens 100 lignes et un 200, pas une erreur — alors relis pagination.pageSize dans la réponse plutôt que de te fier à ce que tu as envoyé.

Une réponse peut porter des champs que cette page ne liste pas. Ignore ceux que tu ne reconnais pas plutôt que de planter dessus — c'est ce qui garde ton client fonctionnel à mesure que l'API s'étoffe.

REST est du HTTP ordinaire, donc aucun SDK n'est nécessaire pour l'appeler — n'importe quel langage avec un client HTTP fait l'affaire. Rien à installer.

Sécurité et gestion des clés

Comptes

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

Solde d'un compte

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

Sommaire des comptes

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

Transactions

{
  "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": [ … ]
}

Catégories

{
  "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": [ … ],
  …
}

Étiquettes

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