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

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. Envoyez-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 vous écriviez. Relisez-la et renvoyez votre é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. 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, 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é, catégories, tags 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.

• 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 vous avez un doute sur une clé, révoquez-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ésumez 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, 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.

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