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. Le voci di una scrittura indicano il tuo account, non la chiave che ha fatto la modifica.

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, per impostazione predefinita quelli reali: totalAssets, totalLiabilities e netWorthHint, che è il primo meno il secondo. Passa simulationModes per scegliere quali modalità contano: l'elenco dei conti e i totali coprono solo quelle che indichi. includedSimulationModes indica quali modalità coprono, in ogni risposta. simulationExcludedAccountCount conta i conti che riesci a vedere e che sono stati lasciati fuori a causa della loro modalità. totalHiddenCount è un conteggio a parte: i conti che il tuo piano o la tua impostazione di visibilità nasconde, in qualsiasi modalità, e mai quelli che simulationModes ha lasciato fuori.

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

netWorthHint conta solo i conti presenti in questa risposta, e due conteggi ti dicono cosa lascia fuori. simulationExcludedAccountCount sono i conti fuori dalle modalità richieste. totalHiddenCount sono i conti che ti vengono nascosti in qualsiasi modalità. Si divide in due: tierExcludedAccountCount per quelli che il limite di conti del tuo piano lascia fuori, e userExcludedAccountCount per quelli che hai nascosto tu. Entrambi sono null se Era non è riuscita a leggere il tuo piano in quella chiamata. 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
}

Non c'è nessuna chiamata che legga una singola transazione tramite il suo id. GET /banking/transactions/{id} risponde 405 con Allow: PUT, perché quel percorso serve solo a modificare una transazione. Per leggerne una, chiedi l'elenco con filtri che la restringano — accountId impostato sul suo accountGroupKey, fromDate e toDate entrambi impostati sulla sua transactionDate, e search sul nome del commerciante o sull'importo — poi trovala tramite il suo id in ciò che torna indietro. Se è un addebito in sospeso recente, aggiungi includePending.

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; i piani a pagamento funzionano con un uso ragionevole. 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
    }
  ]
}

Tutte le regole di automazione del tuo account — quelle che hai creato tu e quelle che Era ti ha impostato dalla sua libreria di regole — ciascuna con le sue condizioni (filters), ciò che fa (actions), se è attiva e la sua versione. Nessuna paginazione: una sola risposta le restituisce tutte. Le regole disattivate restano fuori, a meno che tu non le chieda.

{
  "rules": [
    {
      "id": "rule_4c1e7a90",
      "ruleName": "Coffee shops",
      "isActive": true,
      "version": 3,
      "priority": 10,
      "filters": [{ "type": "merchant_match", "pattern": "Blue Bottle", "mode": "contains" }],
      "actions": [{ "type": "set_category", "categoryKey": "fcat_coffee_shops", "categoryDisplayName": "Coffee shops" }],
      "source": "user",
      "matchedTransactionCount": 42,
      …
    }
  ]
}

filters e actions sono elenchi di oggetti tipizzati. Ognuno indica il suo tipo in un campo type — merchant_match o category tra i filtri, set_category o add_tag tra le azioni — e il documento OpenAPI collegato nell'avvio rapido elenca ogni tipo con i campi che accetta.