API di Era

Avvio rapido

Prima di iniziare ti serve un account Era con almeno un istituto collegato: senza una connessione questi endpoint non hanno niente da restituire.

1. 1

   Accedi a Era e collega un istituto, se non l'hai già fatto.

2. 2

   Apri le tue chiavi API nella dashboard e creane una. All'inizio sono spuntati tutti gli scope, quindi togli la spunta a quelli che non ti servono — per questi endpoint resta banking:read. Scegli anche una scadenza; non esiste un'opzione senza scadenza.

3. 3

   Copia la chiave. Viene mostrata una volta sola e non possiamo mostrartela di nuovo. Copiala e conservala in un posto sicuro, come un gestore di segreti. Se perdi una chiave, non puoi più vederla. Creane una nuova al suo posto.

4. 4

   Mandala in un header insieme alla tua richiesta.

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 disponibili

L'API di Era include le seguenti API:

• GET/banking/accounts

  Ogni account che puoi vedere, su tutte le istituzioni collegate.

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

  Il saldo di un account, con i campi di credito compilati se è una passività.

• GET/banking/accounts/summary

  I totali su tutti gli account che puoi vedere.

• GET/banking/transactions

  Le tue transazioni, una pagina alla volta.

• PUT/banking/transactions/{id}

  Modifica una transazione

• PUT/banking/transactions/bulk

  Modifica fino a 100 alla volta

• GET/banking/categories

  L'intera tassonomia delle categorie, con le sottocategorie annidate.

• POST/banking/categories

  Aggiungi una categoria

• GET/banking/tags

  Tutti i tag del tuo account, in un'unica risposta.

• POST/banking/tags

  Crea un tag

Autenticazione

Invia la tua chiave in uno di questi due modi:

Ogni richiesta è cifrata con TLS.

Le chiavi scadono, e quando ne crei una scegli tu tra quanto. La durata massima disponibile è di 90 giorni sul piano gratuito e di 365 su uno a pagamento: non esiste un'opzione senza scadenza, quindi qualsiasi cosa tu costruisca su questo ha bisogno di un piano per ruotare la chiave prima che scada.

Header di risposta

Un ID richiesta torna su ogni risposta. Gli header di limite tornano sulle chiamate che Era ha misurato. Se Era non riesce a misurare il tuo utilizzo, serve la chiamata e non ne manda nessuno.

Errori

L'API restituisce questi codici di stato di errore:

• 400

  Input malformato: un parametro sbagliato, un aggiornamento massivo vuoto o con più di 100 elementi, o una scrittura che imposta e cancella lo stesso campo nella stessa chiamata.

• 401

  Nessuna chiave, o una che non si può interpretare. Inviala nell'intestazione X-API-Key o come token bearer.

• 402

  Una quota del piano è d'intralcio — oggi succede solo con la creazione di categorie. Riguarda cosa stai creando, non quanto in fretta chiami: aspettare non la sblocca, un piano più grande sì. Chiamare troppo in fretta è invece un 429.

• 403

  La chiave non porta lo scope di cui questa chiamata ha bisogno — oppure, su una delle due scritture di transazioni, l'id appartiene a qualcun altro o non esiste affatto. L'API non distingue i due casi.

• 404

  Un account che non esiste. Lo restituisce solo l'endpoint del saldo: un accountGroupKey che non indica alcun account, o che non ha nemmeno la forma di una chiave, torna come 404 senza corpo. Le transazioni non restituiscono mai 404 — vedi 403.

• 409

  Qualcos'altro ha cambiato la riga mentre stavi scrivendo. Rileggila e reinvia la tua scrittura.

• 429

  Troppe richieste. Hai esaurito il budget giornaliero o raggiunto il tetto di burst al minuto. Retry-After dice quanto aspettare e, a differenza di un 402, aspettare risolve. In Limiti trovi quale limite ha rifiutato e i numeri per piano.

Forme di errore

La maggior parte degli errori torna nella stessa forma: statusCode, message e un oggetto errors che indica cosa non andava. Non tutti: un 401 e un 404 tornano senza alcun corpo, quindi leggi lo stato prima del corpo.

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

ID richiesta

Ogni risposta porta un'intestazione fly-request-id. Includila quando contatti il supporto per una richiesta specifica.

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

Errori comuni

• Impostare un campo e cancellarlo nella stessa scrittura — 400.

• Più di 100 id in un aggiornamento massivo — 400, e non cambia nulla. Meno di uno è lo stesso.

• Una transazione che non è tua, o che non esiste — 403, mai 404. Quindi la risposta non ti dice mai se un id esiste, solo che non è tuo da vedere.

• Qualcos'altro ha cambiato la riga per primo — 409.

Limiti

Due dei dieci endpoint documentati limitano quanto puoi chiedere in una singola chiamata. Gli altri otto no.

Questo non significa illimitato: le chiavi continuano a scadere, le scritture hanno comunque limiti di lunghezza dei campi, la creazione di una categoria può raggiungere una quota del piano, e il tuo piano può comunque nascondere lo storico più vecchio. Niente di tutto questo è un rate limit — vedi sotto.

• Account, saldo, riepilogo, gli elenchi di categorie e tag, la creazione di una categoria, la creazione di un tag e la scrittura di una singola transazione non hanno alcun limite di volume per chiamata. Ricevi l'intero insieme, oppure la singola riga che hai indicato.

• pageSize è limitato a 100, non rifiutato. Chiedine di più e ricevi 100 righe con un 200 — leggi pagination.pageSize nella risposta invece di fidarti di ciò che hai inviato.

• La scrittura massiva delle transazioni è limitata a 100 id, e a differenza di pageSize viene rifiutata anziché limitata: invia 101 e ricevi un 400, senza che nulla cambi.

• Le chiavi scadono secondo il programma che scegli alla creazione — fino a 90 giorni nel piano gratuito, 365 in uno a pagamento. Non esiste un'opzione senza scadenza.

• Il tuo piano può applicare un limite di finestra della cronologia che nasconde le transazioni più vecchie. La risposta delle transazioni porta i campi historyWindow che dicono se un limite si è applicato e dove è caduto.

Rate limit

Ogni piano può chiamare questa API, e ogni piano è misurato. Quello che conta: le chiamate che fai con una chiave. Due limiti valgono insieme — un budget giornaliero e un tetto di burst al minuto — e superarne uno qualsiasi torna come 429.

Il tuo budget giornaliero è tuo, non di una chiave. Ogni chiave REST del tuo account attinge allo stesso budget giornaliero, quindi creare una seconda chiave non ti compra altre chiamate. Le chiamate agli strumenti MCP si contano a parte: spendere le une non spende mai le altre.

Quando Era misura una chiamata, la risposta porta X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Tutti e tre descrivono il tuo budget giornaliero, che scorre sulle 24 ore invece di azzerarsi a mezzanotte: le richieste tornano una alla volta man mano che le tue chiamate più vecchie compiono 24 ore. Il tetto di burst al minuto non ha un header, quindi regola tu il ritmo sul valore della tabella. Remaining può essere ben sopra lo zero mentre un burst torna comunque con un 429. Se Era non riesce a misurare il tuo utilizzo, serve la chiamata e non manda header di rate limit, quindi tratta gli header mancanti come una lettura mancante, non come un errore.

Cosa ti dice un 429

Un body problem-details. Il suo campo detail è testo semplice, non campi strutturati: nomina il limite che hai raggiunto, quanto consente quel limite, quando si libera la tua prossima richiesta e il piano che lo alza, oppure che sei già sul più alto. Non analizzarlo. Per ramificare nel codice, leggi gli header: Remaining a 0 significa che ha rifiutato il budget giornaliero, sopra 0 che è stato il tetto di burst al minuto.

{
  "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 porta anche Retry-After, un numero intero di secondi misurato dal limite che ha rifiutato: fino a un minuto per il tetto di burst al minuto, fino a 24 ore per il budget giornaliero. Una chiamata rifiutata non consuma nulla, quindi riprovare presto non ti costa nulla, ma torna di nuovo con 429. Quando Retry-After è trascorso, si libera una richiesta, non l'intero budget. Inviala, poi leggi gli header o il Retry-After successivo.

Niente di tutto questo protegge una chiave che hai perso di vista. Una chiave trapelata spende il tuo budget esattamente come faresti tu. Se hai un dubbio su una chiave, revocala. Vedi Sicurezza e gestione delle chiavi più sotto.

Convenzioni

I campi delle risposte sono in camelCase. I parametri di query non distinguono maiuscole e minuscole, quindi lì funziona anche il camelCase: la specifica pubblicata li scrive in PascalCase, ed è per questo che in giro vedi entrambe le forme.

Un campo che indica un giorno di calendario è in formato YYYY-MM-DD. Un campo che indica un istante è in ISO 8601 con l'offset.

Le dimensioni delle pagine vengono limitate, non rifiutate. Chiedi un pageSize di 500 e ottieni 100 righe e un 200, non un errore: leggi quindi pagination.pageSize invece di fidarti di quello che hai mandato.

Una risposta può portare campi che questa pagina non elenca. Ignora quelli che non riconosci invece di fallire: è questo che tiene in piedi il tuo client mentre l'API cresce.

REST è semplice HTTP, quindi per chiamarlo non serve nessun SDK: va bene qualsiasi linguaggio con un client HTTP. Non c'è niente da installare.

Versioni e modifiche

Tutto quello che è documentato qui rientra in questa politica.

Non c'è un numero di versione nel percorso né un header di versione. Ogni endpoint ha una sola versione attiva, ed è quella documentata qui.

Cosa possiamo cambiare senza preavviso

Niente di tutto questo rompe un client che segue le convenzioni qui sopra.

• Aggiungere un endpoint, o un'operazione su uno che esiste già.

• Aggiungere un campo a una risposta.

• Aggiungere un parametro opzionale. Omettilo e non cambia niente.

• Aggiungere un valore a un insieme fisso, come uno stato o un tipo.

• Aggiungere un header di risposta.

Cosa non cambiamo senza preavviso

Ognuno di questi può rompere un client che funziona.

• Togliere un endpoint, o cambiarne il percorso o il metodo.

• Togliere o rinominare un campo di risposta.

• Cambiare il tipo di un campo o il suo significato.

• Rendere obbligatorio un parametro oggi opzionale.

• Rifiutare un input oggi accettato.

• Cambiare lo scope che serve a un endpoint.

Prima di ciascuna di queste modifiche, il changelog lo annuncia con almeno 90 giorni di anticipo e ti dice cosa cambiare. Quello che funziona oggi continua a funzionare fino ad allora.

Le modifiche vengono annunciate nel changelog, collegato nella sezione Changelog qui sotto. Non c'è ancora né email né feed, quindi controllalo quando pianifichi lavoro sull'API.

Finché l'API è in beta, l'insieme documentato continuerà a crescere. Quello che c'è già non si romperà senza preavviso.

Changelog

Le novità della Era Developer Platform, inclusa l'API Era, dalla più recente. La policy qui sopra dice cosa viene annunciato in anticipo e con quanto preavviso; il changelog è dove compaiono quegli annunci.

Sicurezza e gestione delle chiavi

Conti

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

Saldo di un conto

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

Riepilogo dei conti

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

Transazioni

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

Categorie

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

Tag

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