Era API

クイックスタート

始める前に、Eraのアカウントと、少なくとも1つの金融機関の接続が必要です。接続がないと、これらのエンドポイントは返すものがありません。

1. 1

   Eraにサインインし、まだなら金融機関を接続します。

2. 2

   ダッシュボードのAPIキーを開いてキーを作成します。スコープは最初からすべてチェックが入っているので、要らないものを外してください。これらのエンドポイントに残すのはbanking:readです。有効期限も選びます。無期限という選択肢はありません。

3. 3

   キーをコピーします。表示は一度だけで、再表示はできません。コピーしてシークレットマネージャーなど安全な場所に保管してください。キーを紛失した場合、二度と表示できません。代わりに新しいキーを作成してください。

4. 4

   リクエストのヘッダーに載せて送ります。

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

Era APIには次のAPIが含まれます：

• GET/banking/accounts

  接続しているすべての金融機関にわたる、閲覧できるすべての口座。

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

  一つの口座の残高。負債の場合はクレジット関連のフィールドも含む。

• GET/banking/accounts/summary

  閲覧できるすべての口座の合計。

• GET/banking/transactions

  取引履歴を、ページ単位で。

• PUT/banking/transactions/{id}

  取引を一件変更する

• PUT/banking/transactions/bulk

  一度に100件まで変更する

• GET/banking/categories

  カテゴリ体系全体。サブカテゴリも入れ子で。

• POST/banking/categories

  カテゴリを追加する

• GET/banking/tags

  アカウントのすべてのタグを、一回のレスポンスで。

• POST/banking/tags

  タグを作成する

認証

キーは次のいずれかの方法で送ってください:

すべてのリクエストはTLSで暗号化されます。

キーには有効期限があり、作るときにどれくらいで切れるかを選びます。最長は無料プランで90日、有料プランで365日です。無期限という選択肢はないので、これを使って作るものには、期限が来る前にキーを入れ替える段取りが要ります。

レスポンスヘッダー

すべてのレスポンスには次が含まれます:

エラー

このAPIが返すエラーのステータスコードは次のとおりです：

• 400

  不正な入力: パラメータの誤り、空または100件を超える一括更新、あるいは同じ呼び出しで同じフィールドを設定と解除の両方を行う書き込み。

• 401

  キーがない、または解析できないキー。X-API-Keyヘッダーかベアラートークンとして送ってください。

• 402

  プランのクォータに引っかかっています — 現時点ではカテゴリ作成にのみ当てはまります。

• 403

  キーがこの呼び出しに必要なスコープを持っていない — または、二つの取引書き込みのいずれかで、idが他人のものか、そもそも存在しない場合。APIはこの二つを区別しません。

• 409

  書き込み中に別の何かがその行を変更しました。もう一度読み込んで、もう一度書き込んでください。

エラーの形

すべてのエラーは同じ形で返ります: statusCode、message、そして何が問題だったかを示すerrorsオブジェクトです。キーがない、または無効な場合は、本文なしで返ることもあります。

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

リクエストID

すべてのレスポンスにはfly-request-idヘッダーが付きます。特定のリクエストについてサポートに連絡する際はこれを伝えてください。

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

よくあるエラー

• 同じ書き込みでフィールドを設定と解除の両方を行う — 400。

• 一括更新で100件を超えるid — 400、何も変更されません。1件未満も同様です。

• 自分のものではない、あるいは存在しない取引 — 403、404にはなりません。つまりレスポンスは、そのidが存在するかどうかを決して教えず、ただ「あなたのものではない」とだけ伝えます。

• 他の何かが先にその行を変更した — 409。

制限

ドキュメント化された10のエンドポイントのうち2つは、1回の呼び出しでリクエストできる量に上限があります。残りの8つにはありません。

上限がないからといって無制限というわけではありません: キーには引き続き有効期限があり、書き込みには引き続きフィールド長の制限があり、プランによっては古い履歴が引き続き隠されることがあります。これらはいずれもレート制限ではありません — 下記を参照してください。

• アカウント、残高、サマリー、カテゴリ、タグ、そして単一トランザクションの書き込みには、呼び出しごとの量的な上限がありません。指定したセット全体、または指定した1行がそのまま返されます。

• pageSizeは拒否ではなく100に切り詰められます。それ以上を要求しても、200とともに100件が返ってきます — 送った値を信じるのではなく、レスポンスのpagination.pageSizeを読んでください。

• 取引の一括書き込みは100件のidに制限されており、pageSizeと違って切り詰めではなく拒否されます: 101件送ると400が返り、何も変更されません。

• キーは作成時に選んだスケジュールで期限切れになります — 無料プランで最大90日、有料プランで365日です。無期限のオプションはありません。

• プランによっては、古い取引を隠す履歴ウィンドウの下限が適用されることがあります。取引のレスポンスには、下限が適用されたかどうかとその位置を示すhistoryWindowフィールドが含まれます。

• プランはAPIリクエストの割り当ても示します — 無料プランで500件、有料プランではさらに多くなります。

ここにないもの: 現時点ではRESTにリクエスト単位のスロットリングはなく、429も、レート制限ヘッダーもありません — つまり漏えいしたキーは、こちら側の仕組みでは何にも減速されません。キーについて少しでも不安があれば、取り消してください: それで即座に遮断されます（上のセキュリティとキー管理を参照）。そしてこのAPIはベータ版なので、それがずっと続くとは思わないでください。

共通の決まり

レスポンスのフィールドはcamelCaseです。クエリパラメータは大文字と小文字を区別しないので、こちらもcamelCaseで通ります。公開している仕様書ではPascalCaseで書かれているため、両方の書き方を見かけることになります。

暦の上の一日を指すフィールドはYYYY-MM-DDです。ある瞬間を指すフィールドは、オフセット付きのISO 8601です。

ページの大きさは、はねつけられるのではなく丸められます。pageSizeに500を指定しても、返るのは100件と200であって、エラーではありません。送った値を信じるのではなく、pagination.pageSizeを読み返してください。

レスポンスには、このページに載っていないフィールドが入っていることがあります。知らないものはエラーにせず読み飛ばしてください。そうしておけば、APIが広がっても手元のクライアントは動き続けます。

RESTは素のHTTPなので、呼び出すのにSDKは要りません。HTTPクライアントのある言語ならどれでも大丈夫です。インストールするものはありません。

セキュリティとキーの扱い

口座

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

口座の残高

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

口座のまとめ

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

取引

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

カテゴリ

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

タグ

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