API Era

Démarrage rapide

Avant de commencer, il vous faut un compte Era avec au moins un établissement connecté — sans connexion, ces points de terminaison n'ont rien à renvoyer.

1. 1

   Connectez-vous à Era et reliez un établissement, si ce n'est pas déjà fait.

2. 2

   Ouvrez vos clés d'API dans le tableau de bord et créez une clé. Toutes les portées sont cochées au départ, donc décochez celles dont vous n'avez pas besoin — pour ces points de terminaison, il ne reste que banking:read. Vous choisissez aussi une expiration ; il n'existe pas d'option « n'expire jamais ».

3. 3

   Copiez la clé. Elle ne s'affiche qu'une fois, et nous ne pouvons pas la réafficher. Copiez-la et conservez-la en lieu sûr, par exemple dans un gestionnaire de secrets. Si vous perdez une clé, vous ne pouvez plus la consulter. Créez-en une nouvelle à la place.

4. 4

   Envoyez-la dans un en-tête avec votre 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 vous pouvez voir, sur tous vos é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 vous pouvez voir.

• GET/banking/transactions

  Vos 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 votre compte, en une seule réponse.

• POST/banking/tags

  Créer une étiquette

Authentification

Envoyez votre clé de l'une de ces deux façons :

Chaque requête est chiffrée avec TLS.

Les clés expirent, et vous choisissez au bout de combien de temps au moment de les créer. 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 », donc tout ce que vous construisez là-dessus doit prévoir la rotation de la clé avant qu'elle n'expire.

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 votre 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. Envoyez-la dans l'en-tête X-API-Key ou comme jeton bearer.

• 402

  Un quota de forfait fait obstacle — aujourd'hui, cela ne concerne que la création de catégories. Il s'agit de ce que vous créez, pas de la vitesse à laquelle vous appelez : attendre n'y change rien, un forfait supérieur si. 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 vous écriviez. Relisez-la et renvoyez votre écriture.

• 429

  Trop de requêtes. Vous avez épuisé votre 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 lisez 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. Indiquez-le lorsque vous contactez 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 vôtre, ou qui n'existe pas — 403, jamais 404. La réponse ne vous dit donc jamais si un id existe, seulement qu'il n'est pas à vous.

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

Limites

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

Cela 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 votre forfait peut toujours masquer l'historique ancien. Rien de tout cela n'est une limite de débit — voir ci-dessous.

• 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. Vous recevez l'ensemble complet, ou la seule ligne que vous avez nommée.

• pageSize est plafonné à 100, jamais refusé. Demandez-en plus et vous recevez 100 lignes avec un 200 — lisez pagination.pageSize dans la réponse plutôt que de faire confiance à ce que vous avez envoyé.

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

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

• Votre 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 vous faites 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.

Votre budget quotidien vous appartient, pas à une clé. Toutes les clés REST de votre compte puisent dans le même budget quotidien : créer une deuxième clé ne vous 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 votre 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 vos plus anciens appels atteignent 24 heures. Le plafond de rafale par minute n'a pas d'en-tête, alors réglez vous-même votre 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 votre usage, l'appel est servi sans aucun en-tête de limite : considérez 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 votre prochaine requête se libère, et le forfait qui la relève, ou le fait que vous êtes déjà sur le plus haut. Ne l'analysez pas. Pour brancher votre code, lisez 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 vous 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. Envoyez-la, puis lisez les en-têtes ou le prochain Retry-After.

Rien de tout cela ne protège une clé que vous avez perdue de vue. Une clé qui a fuité dépense votre budget exactement comme vous le feriez. Si vous avez un doute sur une clé, révoquez-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, donc le camelCase fonctionne là aussi — la spécification publiée les écrit en PascalCase, et c'est pour cela que vous verrez les deux formes circuler.

Un champ qui désigne un jour de calendrier est en YYYY-MM-DD. Un champ qui désigne 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. Demandez un pageSize de 500 et vous obtenez 100 lignes et un 200, pas une erreur — donc relisez pagination.pageSize dans la réponse plutôt que de vous fier à ce que vous avez envoyé.

Une réponse peut porter des champs que cette page ne liste pas. Ignorez ceux que vous ne reconnaissez pas plutôt que d'échouer dessus — c'est ce qui garde votre client fonctionnel à mesure que l'API s'étoffe.

REST, c'est du HTTP ordinaire, donc aucun SDK n'est nécessaire pour l'appeler — n'importe quel langage doté d'un client HTTP fait l'affaire. Il n'y a 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. Omettez-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 vous 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 d'e-mail ni de flux, alors consultez-le quand vous planifiez 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 vous 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
}

Synthèse 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"
  }
}