API da Era

Aprovar um agente cria uma chave

Quando você aprova um agente por OAuth, a Era cria uma chave de API para ele. Ela aparece na mesma lista do painel que as suas, com um nome que a Era monta a partir do nome do próprio cliente.

Ela carrega exatamente os escopos que você aprovou naquela tela, e nada além. Revogue pelo painel e o agente não consegue obter novo acesso até você aprová-lo de novo. Um token que ele já tem continua funcionando até expirar, no máximo em uma hora.

Escritas aparecem no seu registro de atividade, leituras não

Criar e revogar uma chave aparecem no seu registro de atividade, assim como cada chamada de ferramenta que um agente faz por MCP. Uma escrita REST também aparece — como a mudança que ela fez, uma tag criada ou uma transação editada. Uma leitura REST não cria nenhuma entrada. A Era registra essas entradas em qualquer plano, mas ler o registro completo exige Organize ou superior — abaixo disso você vê só as entradas mais recentes. As entradas de uma escrita mostram a sua conta, não a chave que fez a mudança.

Se você ficar em dúvida sobre uma chave, revogue. Uma chave que você mesmo criou para de funcionar no REST e no MCP a partir da próxima requisição. A chave de um agente para de obter novo acesso na hora, e qualquer token que ele já tenha expira em menos de uma hora. Criar outra leva um minuto.

Todas as contas que você consegue ver, em cada instituição conectada, com a contagem das que ficaram de fora ao lado delas: excludedAccountCount, dividida em tierExcludedAccountCount para as contas que o limite de contas do seu plano deixa de fora e userExcludedAccountCount para as que você escondeu. accountLimit é quantas contas o seu plano mostra de uma vez, somando todas as suas conexões. accountLimitLift traz o nome do plano mais barato com espaço para todas as contas que você não escondeu, e vem null quando o seu plano não deixa nada de fora. Cada conta carrega o seu accountGroupKey — o valor que o endpoint de saldo recebe no caminho — e o connectionId ao qual ela pertence, então esta é a primeira chamada a fazer. Aceita connectionId para restringir a uma única conexão (as contagens se restringem junto; accountLimit e accountLimitLift não), e includeExcluded para trazer as contas que o seu plano deixa de fora e as que você escondeu.

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

Em uma conta que você escondeu ou que o seu plano exclui, os campos de saldo voltam como null, não como zero — null quer dizer retido, não vazio. supportsTransactions vem null no mesmo espírito: quer dizer que a Era não tem como afirmar, nunca que a resposta é não. O mesmo vale para os campos do plano: se a Era não conseguiu ler o seu plano naquela chamada, tierExcludedAccountCount, userExcludedAccountCount, accountLimit e accountLimitLift voltam todos como null. accountLimit também vem null num plano sem limite de contas, e accountLimitLift quando nenhum plano tem mais espaço ou quando o seu plano não deixa nada de fora.

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
}

Uma conta escondida, ou uma cuja conexão foi cortada, ainda responde 200 — com os campos de saldo em null. Um 404 significa que a conta realmente não existe, ou que a chave não tinha formato de chave. Repare aqui no campo visibility: ele é null quando a conta está visível, tier_excluded quando o limite de contas do seu plano a deixa de fora, user_excluded quando você a escondeu e connection_severed quando a conexão dela foi cortada. Com tier_excluded, accountLimit é o limite do seu plano e accountLimitLift traz o nome do plano mais barato com espaço para todas as contas que você não escondeu, incluindo esta. accountLimitLift vem null em qualquer outro estado, e com connection_severed accountLimit também vem null.

Os totais das contas que você consegue ver, por padrão as reais: totalAssets, totalLiabilities e netWorthHint, que é o primeiro menos o segundo. Passe simulationModes para escolher quais modos contam: a lista de contas e os totais cobrem só os que você indicar. includedSimulationModes diz quais modos eles cobrem, em cada resposta. simulationExcludedAccountCount conta as contas que você consegue ver e que ficaram de fora por causa do modo. totalHiddenCount é uma contagem à parte: as contas que o seu plano ou a sua própria configuração de visibilidade esconde, em qualquer modo, e nunca as que simulationModes deixou de fora.

{
  "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 só as contas desta resposta, e duas contagens dizem o que ele deixa de fora. simulationExcludedAccountCount são as contas fora dos modos que você pediu. totalHiddenCount são as contas escondidas de você em qualquer modo. Ela se divide em duas: tierExcludedAccountCount para as que o limite de contas do seu plano deixa de fora, e userExcludedAccountCount para as que você mesmo escondeu. As duas vêm null se a Era não conseguiu ler o seu plano naquela chamada. accountLimitLift traz o nome do plano mais barato que traz as primeiras de volta, e vem null quando não há nenhuma. Trate netWorthHint como um número de partida, não como o seu patrimônio líquido definitivo.

Suas transações, uma página por vez, embrulhadas junto com as contagens de paginação. Aceita page e pageSize (100 é o teto), além de filtros opcionais por conta, período, regras aplicadas e etiquetas atribuídas.

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

Seu plano pode aplicar um corte de janela de histórico, que esconde as transações mais antigas que ele. É por isso que a resposta traz os campos historyWindow: historyWindowApplied diz que o corte realmente escondeu algo, historyWindowFloorDate é onde ele caiu, historyWindowHiddenCount é quantas linhas ficaram atrás, e historyWindowEarliestDate é até onde o seu histórico vai de verdade. Sem eles, um resultado curto é indistinguível de uma conta sem transações mais antigas. Dois deles mudam o que você escreve: historyWindowHiddenCount pode vir como null mesmo quando um corte foi aplicado, então leia null como desconhecido, não como zero; e quando historyWindowDegraded é true, a Era não conseguiu confirmar seu plano naquela leitura, então a data do corte é um palpite, não um fato. Numa leitura paga confirmada, nenhum corte é aplicado e historyWindowApplied volta como false. O limite de contas do seu plano também deixa transações de fora: tierExcludedAccountCount diz quantas das suas contas ele deixa fora desta leitura, e userExcludedAccountCount quantas você escondeu — as duas restritas à conta que você filtrou, se filtrou alguma. As duas vêm null quando a Era não conseguiu ler o seu plano naquela chamada.

Percorrer um histórico longo gasta requisições. Seu plano limita a velocidade com que você pode chamar e, no plano gratuito, quantas chamadas você tem por dia; os planos pagos funcionam com uso justo. Em Limites estão os números por plano, os cabeçalhos de limite e o que um 429 te diz.

Toda a taxonomia de categorias: cada conjunto de categorias, com as subcategorias aninhadas dentro. A taxonomia é compartilhada, não por conta.

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

Todas as etiquetas da sua conta, em uma lista só. Sem paginação — uma única resposta devolve todas.

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

Todas as regras de automação da sua conta — as que você criou e as que a Era configurou para você a partir da biblioteca de regras dela —, cada uma com suas condições (filters), o que ela faz (actions), se está ligada e a versão. Sem paginação: uma única resposta devolve todas. Regras desligadas ficam de fora, a menos que você peça.

{
  "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 são listas de objetos tipados. Cada um diz o seu tipo em um campo type — merchant_match ou category entre os filtros, set_category ou add_tag entre as ações —, e o documento OpenAPI linkado no início rápido lista todos os tipos e os campos que cada um aceita.