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

Un ID de requête revient sur chaque réponse. Les en-têtes de limite reviennent sur les appels qu'Era a mesurés. Si Era ne peut pas mesurer ton usage, l'appel est servi sans aucun de ces en-têtes.

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 de forfait fait obstacle — aujourd'hui, ça ne concerne que la création de catégories. Il s'agit de ce que tu crées, pas de la vitesse à laquelle tu appelles : attendre n'y change rien, un forfait supérieur oui. Appeler trop vite, c'est un 429.

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

• 404

  Un compte qui n'existe pas. Seul l'endpoint de solde le renvoie : un accountGroupKey qui ne désigne aucun compte, ou qui n'a même pas la forme d'une clé, revient en 404 sans corps. Les transactions ne renvoient jamais 404 — voir 403.

• 409

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

• 429

  Trop de requêtes. Tu as épuisé ton budget quotidien ou atteint le plafond de rafale par minute. Retry-After indique combien de temps attendre et, contrairement à un 402, attendre règle le problème. Voir Limites pour savoir quelle limite a refusé et pour les chiffres par forfait.

Formes d'erreur

La plupart des erreurs reviennent sous la même forme : statusCode, message et un objet errors qui nomme ce qui n'allait pas. Pas toutes : un 401 et un 404 reviennent sans corps du tout, alors lis le statut avant de lire le corps.

{
  "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, la création d'une catégorie peut atteindre un quota de forfait, 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é, les listes de catégories et de tags, la création d'une catégorie, la création d'un tag 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.

Limites de débit

Tous les forfaits peuvent appeler cette API, et tous sont mesurés. Ce qui compte : les appels que tu fais avec une clé. Deux limites s'appliquent en même temps — un budget quotidien et un plafond de rafale par minute — et dépasser l'une ou l'autre renvoie un 429.

Ton budget quotidien t'appartient, pas à une clé. Toutes les clés REST de ton compte puisent dans le même budget quotidien : créer une deuxième clé ne t'achète donc pas d'appels supplémentaires. Les appels d'outils MCP sont comptés à part — dépenser l'un ne dépense jamais l'autre.

Quand Era mesure un appel, la réponse porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Les trois décrivent ton budget quotidien, qui se renouvelle en continu sur 24 heures au lieu de repartir à zéro à minuit : les requêtes reviennent une à une à mesure que tes plus anciens appels atteignent 24 heures. Le plafond de rafale par minute n'a pas d'en-tête, alors règle toi-même ton rythme d'après le chiffre du tableau. Remaining peut afficher bien plus que zéro alors qu'une rafale revient quand même en 429. Si Era ne peut pas mesurer ton usage, l'appel est servi sans aucun en-tête de limite : considère donc l'absence d'en-têtes comme une mesure manquante, pas comme une erreur.

Ce que dit un 429

Un corps problem-details. Son champ detail est du texte brut, pas des champs structurés : il nomme la limite atteinte, ce qu'elle autorise, quand ta prochaine requête se libère, et le forfait qui la relève, ou le fait que tu es déjà sur le plus haut. Ne l'analyse pas. Pour brancher ton code, lis les en-têtes : Remaining à 0 veut dire que le budget quotidien a refusé, et au-dessus de 0, que c'est le plafond de rafale par minute.

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

Un 429 porte aussi Retry-After, un nombre entier de secondes mesuré depuis la limite qui a refusé : jusqu'à une minute pour le plafond de rafale par minute, jusqu'à 24 heures pour le budget quotidien. Un appel refusé ne consomme rien, donc réessayer trop tôt ne te coûte rien, mais il reviendra en 429. Une fois le délai de Retry-After écoulé, une requête se libère, pas le budget entier. Envoie-la, puis lis les en-têtes ou le prochain Retry-After.

Rien de tout ça ne protège une clé que tu as perdue de vue. Une clé qui a fuité dépense ton budget exactement comme tu le ferais. Si tu as un doute sur une clé, révoque-la. Voir Sécurité et gestion des clés plus bas.

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.

Versionnage et changements

Tout ce qui est documenté ici relève de cette politique.

Il n'y a pas de numéro de version dans le chemin ni d'en-tête de version. Chaque point de terminaison a une seule version active, et c'est celle documentée ici.

Ce que nous pouvons changer sans préavis

Rien de tout cela ne casse un client qui suit les conventions ci-dessus.

• Ajouter un point de terminaison, ou une opération sur un point existant.

• Ajouter un champ à une réponse.

• Ajouter un paramètre facultatif. Omets-le et rien ne change.

• Ajouter une valeur à un ensemble fixe, comme un statut ou un type.

• Ajouter un en-tête de réponse.

Ce que nous ne changeons pas sans préavis

Chacun de ces changements peut casser un client qui fonctionne.

• Retirer un point de terminaison, ou changer son chemin ou sa méthode.

• Retirer ou renommer un champ de réponse.

• Changer le type d'un champ ou sa signification.

• Rendre obligatoire un paramètre aujourd'hui facultatif.

• Refuser une entrée acceptée aujourd'hui.

• Changer la portée dont un point de terminaison a besoin.

Avant chacun de ces changements, le changelog l'annonce au moins 90 jours à l'avance et te dit quoi modifier. Ce qui fonctionne aujourd'hui continue de fonctionner jusque-là.

Les changements sont annoncés dans le changelog, dont le lien se trouve dans la section Changelog ci-dessous. Il n'y a pas encore de courriel ni de flux, alors consulte-le quand tu planifies du travail sur l'API.

Tant que l'API est en bêta, l'ensemble documenté continuera de s'étoffer. Ce qui est déjà là ne cassera rien chez toi sans préavis.

Changelog

Les nouveautés de l'Era Developer Platform, dont l'API Era, du plus récent au plus ancien. La politique ci-dessus dit ce qui est annoncé à l'avance et avec quel délai ; le changelog est l'endroit où ces annonces paraissent.

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