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日です。無期限という選択肢はないので、これを使って作るものには、期限が来る前にキーを入れ替える段取りが要ります。

レスポンスヘッダー

リクエストIDはすべてのレスポンスに付きます。レート制限ヘッダーはEraが計測した呼び出しに付きます。Eraが利用状況を計測できない場合は、呼び出しをそのまま処理し、これらのヘッダーは一切送りません。

エラー

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

• 400

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

• 401

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

• 402

  プランのクォータに引っかかっています — 現時点ではカテゴリ作成にのみ当てはまります。呼び出す速さではなく、何を作るかの話なので、待っても解消せず、上位プランなら解消します。呼び出しが速すぎる場合は、代わりに429になります。

• 403

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

• 404

  存在しない口座です。返すのは残高エンドポイントだけで、どの口座も指していない accountGroupKey や、そもそもキーの形をしていない値は、ボディなしの404で返ります。取引が404を返すことはありません — 403を参照してください。

• 409

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

• 429

  リクエストが多すぎます。1日の予算を使い切ったか、1分あたりのバースト上限に達しました。待つ時間はRetry-Afterでわかり、402とは違い、こちらは待てば解消します。どの上限で拒否されたかとプランごとの数値は、制限の節を参照してください。

エラーの形

ほとんどのエラーは同じ形で返ります: statusCode、message、そして何が問題だったかを示すerrorsオブジェクトです。すべてではありません。401と404は本文なしで返るので、本文より先にステータスを読んでください。

{
  "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を呼び出せますが、どのプランも使用量が計測されます。数えられるのは、キーを使ったあなたの呼び出しです。1日の予算と1分あたりのバースト上限という2つの上限が同時に適用され、どちらかを超えると429が返ります。

1日の予算はキーではなく、あなたに紐づきます。アカウント内のすべてのRESTキーが同じ1日の予算を共有するので、キーをもう1本作っても呼び出せる回数は増えません。MCPツールの呼び出しは別枠で計測されるため、一方を使っても、もう一方は減りません。

Eraが呼び出しを計測した場合、レスポンスにはX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetが付きます。3つとも1日の予算についての値です。この予算は深夜0時にリセットされるのではなく、24時間単位で順に戻ります: 古い呼び出しが24時間を経過するたびに、リクエストが1件ずつ戻ってきます。1分あたりのバースト上限にはヘッダーがないので、表の数値をもとに自分でペースを調整してください。Remainingがゼロを大きく上回っていても、バーストが429で返ってくることがあります。Eraが利用状況を計測できない場合は、呼び出しをそのまま処理し、レート制限ヘッダーは送りません。ヘッダーがないときはエラーではなく、計測値が欠けているものとして扱ってください。

429が伝えること

problem-details形式のボディです。detailフィールドは構造化されたフィールドではなく、プレーンテキストです: 達した上限、その上限で許される量、次のリクエストが空く時刻、そして上限を引き上げるプラン（すでに最上位ならその旨）が書かれています。解析はしないでください。コードで分岐するにはヘッダーを読みます: Remainingが0なら1日の予算で拒否され、0より大きければ1分あたりのバースト上限で拒否されています。

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

429にはRetry-Afterも付きます。拒否した上限を基準にした秒数の整数で、1分あたりのバースト上限なら最大1分、1日の予算なら最大24時間です。拒否された呼び出しは何も消費しないので、早めに再試行しても損はありませんが、また429が返ります。Retry-Afterが経過すると空くのはリクエスト1件分で、予算全体ではありません。それを送ってから、ヘッダーか次のRetry-Afterを読んでください。

これらは、見失ったキーを守ってはくれません。漏えいしたキーは、あなた自身とまったく同じようにあなたの予算を消費します。キーに不安があれば、失効させてください。詳しくは下のセキュリティとキーの扱いを参照してください。

共通の決まり

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

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

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

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

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

バージョンと変更

このページに書かれているものはすべて、この方針の対象です。

パスにバージョン番号はなく、バージョン用のヘッダーもありません。各エンドポイントで動いているバージョンはひとつで、それがここに書かれているものです。

予告なく変えることがあるもの

どれも、上の規約に沿ったクライアントを壊しません。

• エンドポイントを追加する、または既存のものに操作を追加する。

• レスポンスにフィールドを追加する。

• 任意のパラメータを追加する。指定しなければ何も変わらない。

• 決まった選択肢に値を追加する。ステータスや種別など。

• レスポンスヘッダーを追加する。

予告なく変えないもの

どれも動いているクライアントを壊しうるものです。

• エンドポイントをなくす、またはパスやメソッドを変える。

• レスポンスのフィールドをなくす、または名前を変える。

• フィールドの型や意味を変える。

• 今は任意のパラメータを必須にする。

• 今は受け付けている入力を拒否する。

• エンドポイントに必要なスコープを変える。

これらの変更を行う前には、少なくとも90日前に変更履歴でお知らせし、何を変更すべきかをお伝えします。今動いているものは、それまで動き続けます。

変更は変更履歴でお知らせします。リンクは下の「変更履歴」セクションにあります。メールやフィードはまだないので、APIに対する作業を計画するときはそちらをご確認ください。

APIがベータのあいだ、書かれている範囲は広がり続けます。すでにここにあるものが、予告なく壊れることはありません。

変更履歴

Era Developer Platform（Era APIを含む）の更新を、新しい順に。上の方針は何をどれだけ前に予告するかを定めるもので、変更履歴はその予告が載る場所です。

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

口座

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