API di Era

Approvare un agente crea una chiave

Quando approvi un agente tramite OAuth, Era crea una chiave API per lui. Finisce nella stessa lista della dashboard delle chiavi che crei tu, con un nome che Era genera dal nome del client stesso.

Porta esattamente gli scope che hai approvato su quella schermata, e nient'altro. Revocala dalla dashboard e l'agente non potrà ottenere nuovo accesso finché non lo approvi di nuovo. Un token che ha già continua a funzionare fino alla scadenza, al massimo un'ora.

Le scritture compaiono nel tuo registro attività, le letture no

La creazione e la revoca di una chiave compaiono entrambe nel tuo registro attività, e lo stesso vale per ogni chiamata a uno strumento che un agente fa tramite MCP. Compare anche una scrittura REST — come la modifica che ha fatto, per esempio un tag creato o una transazione modificata. Una lettura REST non crea alcuna voce. Era registra queste voci su ogni piano, ma per leggere il registro completo serve Organize o superiore: sotto vedi solo le voci più recenti. Anche per una scrittura REST non tiene un log per singola richiesta: viene registrata la modifica, non la chiamata, e resta sotto il tuo account, non sotto la chiave che l'ha fatta.

Se hai un dubbio su una chiave, revocala. Una chiave creata da te smette di funzionare su REST e su MCP dalla sua richiesta successiva. La chiave di un agente smette subito di ottenere nuovo accesso, e qualsiasi token che ha già scade entro un'ora. Crearne una nuova richiede un minuto.

Tutti i conti che riesci a vedere, su ogni istituto collegato, con accanto il conteggio di quelli rimasti fuori: excludedAccountCount, diviso in tierExcludedAccountCount per i conti che il limite di conti del tuo piano lascia fuori e userExcludedAccountCount per quelli che hai nascosto. accountLimit è quanti conti mostra il tuo piano alla volta, su tutte le tue connessioni. accountLimitLift indica il piano più economico con spazio per tutti i conti che non hai nascosto, ed è null quando il tuo piano non lascia fuori niente. Ogni conto porta con sé il suo accountGroupKey — il valore che l'endpoint del saldo accetta nel percorso — e il connectionId a cui appartiene, quindi è da questa chiamata che si parte. Accetta connectionId per restringere a una sola connessione (i conteggi si restringono con lui, accountLimit e accountLimitLift no) e includeExcluded per far rientrare i conti che il tuo piano lascia fuori e quelli che hai nascosto.

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

Su un conto che hai nascosto o che il tuo piano esclude, i campi del saldo tornano null e non zero: null vuol dire trattenuto, non vuoto. supportsTransactions è null nello stesso spirito: vuol dire che Era non può dirlo, mai che la risposta sia no. Lo stesso vale per i campi del piano: se Era non è riuscita a leggere il tuo piano in quella chiamata, tierExcludedAccountCount, userExcludedAccountCount, accountLimit e accountLimitLift tornano tutti null. accountLimit è null anche su un piano senza limite di conti, e accountLimitLift quando nessun piano ha più spazio o quando il tuo piano non lascia fuori niente.

One account's balance, with the credit fields filled in when the account is a liability. The path takes that account's accountGroupKey — the same value /banking/accounts returns for it. The key is not checked for shape before the lookup, so a malformed key and an unknown one answer the same way.

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

Un conto nascosto, o uno la cui connessione è stata interrotta, risponde comunque 200 — con i campi del saldo a null. Un 404 significa che il conto davvero non c'è, oppure che la chiave non aveva la forma di una chiave. Qui tieni d'occhio il campo visibility: è null quando il conto è visibile, tier_excluded quando il limite di conti del tuo piano lo lascia fuori, user_excluded quando l'hai nascosto tu e connection_severed quando la sua connessione è stata interrotta. Con tier_excluded, accountLimit è il limite del tuo piano e accountLimitLift indica il piano più economico con spazio per tutti i conti che non hai nascosto, questo compreso. accountLimitLift è null in ogni altro stato, e con connection_severed anche accountLimit è null.

I totali sui conti che riesci a vedere: totalAssets, totalLiabilities e netWorthHint, che è il primo meno il secondo. Non accetta parametri.

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

netWorthHint conta solo i conti presenti in questa risposta, quindi è totalHiddenCount a dirti cosa gli manca: tierExcludedAccountCount di questi li lascia fuori il limite di conti del tuo piano, e userExcludedAccountCount li hai nascosti tu. accountLimitLift indica il piano più economico che riporta dentro i primi, ed è null quando non ce ne sono. Tratta netWorthHint come una cifra di partenza, non come un patrimonio netto definitivo.

Le tue transazioni, una pagina alla volta, avvolte in un contenitore che porta accanto i conteggi di paginazione. Accetta page e pageSize (100 è il massimo), più filtri opzionali per conto, intervallo di date, regole applicate e tag assegnati.

{
  "transactions": [ … ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 412,
    "totalPages": 21
  },
  "historyWindowApplied": true,
  "historyWindowFloorDate": "2026-06-28",
  "historyWindowHiddenCount": 137,
  "historyWindowEarliestDate": "2024-03-02",
  "historyWindowDegraded": false
}

Il tuo piano può applicare un limite alla finestra di cronologia, che nasconde le transazioni più vecchie di quella soglia. È per questo che la risposta porta con sé i campi historyWindow: historyWindowApplied ti dice che un limite ha davvero nascosto qualcosa, historyWindowFloorDate è dove è caduto, historyWindowHiddenCount è quante righe ci sono dietro e historyWindowEarliestDate è fin dove arriva davvero la tua cronologia. Senza di loro un risultato corto è indistinguibile da un conto senza transazioni più vecchie. Due di questi cambiano il codice che scrivi: historyWindowHiddenCount può essere null anche quando un limite è stato applicato, quindi leggi null come sconosciuto e non come zero; e quando historyWindowDegraded è true, su quella lettura Era non è riuscita a confermare il tuo piano, quindi la data del limite è una stima e non un dato certo. Su una lettura a pagamento con il piano confermato non si applica nessun limite e historyWindowApplied torna false. Anche il limite di conti del tuo piano lascia fuori delle transazioni: tierExcludedAccountCount ti dice quanti dei tuoi conti tiene fuori da questa lettura, e userExcludedAccountCount quanti ne hai nascosti, entrambi ristretti al conto su cui filtri, se ne filtri uno. Entrambi sono null quando Era non è riuscita a leggere il tuo piano in quella chiamata.

Scorrere una cronologia lunga consuma richieste. Il tuo piano limita quanto velocemente puoi chiamare e, sul piano gratuito, quante chiamate hai al giorno. In Limiti trovi i numeri per piano, gli header di limite e cosa ti dice un 429.

L'intera tassonomia delle categorie: ogni insieme di categorie, con le sue sottocategorie annidate dentro. La tassonomia è condivisa, non è per singolo conto.

{
  "packs": [
    {
      "packSlug": "default",
      "packName": "Era default categories",
      "isDefault": true,
      "categories": [
        {
          "projectionKey": "fcat_food_dining",
          "categoryName": "Food & dining",
          "isTopLevel": true,
          "children": [ … ]
        }
      ]
    }
  ],
  "meterLimit": 25,
  "canCreateCustomCategories": true
}

Tutti i tag del tuo account, in un unico elenco. Nessuna paginazione: una sola risposta li restituisce tutti.

{
  "tags": [
    {
      "tagKey": "utag_9c2f01ab",
      "name": "business-expense",
      "displayName": "Business expense",
      "tagType": "user",
      "color": "#6DC6BA",
      "transactionCount": 42
    }
  ]
}