Era API documentation

Still in beta

These endpoints work today, but the API is still evolving, so some details may change. Check the last-updated date at the top to see when this page was most recently revised.

Quickstart

Before you start you need an Era account with at least one connected institution — without a connection these endpoints have nothing to return.

1
Sign in to Era and connect an institution, if you haven't already.
2
Open your API keys in the dashboard and create a key. Every scope is ticked to start with, so untick the ones you don't need — for these endpoints that leaves banking:read. You also pick an expiry; there's no never-expires option.
3
Copy the key. It's shown once, and we can't show it again. Copy it and store it somewhere safe, such as a secrets manager. If you lose a key, you can't view it again. Create a new key instead.
4
Send it in a header with your request.

cURL

curl "https://forge.era.app/api/banking/transactions?page=1&pageSize=20" \
  -H "X-API-Key: fmk_your_key_here"

Response · 200

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

Make a key

Available APIs

The Era API includes the following APIs:

GET/banking/accounts
Every account you can see, across every connected institution.
GET/banking/accounts/{accountId}/balance
One account's balance, including credit fields on a liability.
GET/banking/accounts/summary
Totals across every account you can see.
GET/banking/transactions
Your transactions, a page at a time.
PUT/banking/transactions/{id}
Change one transaction
PUT/banking/transactions/bulk
Change up to 100 at once
GET/banking/categories
The whole category taxonomy, packs and sub-categories nested.
POST/banking/categories
Add a category
GET/banking/tags
Every tag on your account, in one response.
POST/banking/tags
Create a tag

Authentication

Send your key either of two ways:

Authentication methods
Method	Credential
Header	X-API-Key: fmk_your_key_here
Bearer token	Authorization: Bearer fmk_your_key_here

Every request is encrypted with TLS.

Keys expire, and you choose how soon when you make one. The longest available is 90 days on the free plan and 365 on a paid one — there is no never-expires option, so anything you build against this needs a plan for rotating the key before it lapses.

Response headers

A request id comes back on every response. The rate-limit headers come back on the calls Era metered. If Era can't measure your usage, it serves the call and sends none of them.

Response headers
Header	Description
fly-request-id	A unique identifier for the request. Include it when you contact support about a specific request — see Request ID
X-RateLimit-Limit	Your plan's daily budget.
X-RateLimit-Remaining	What's left of your daily budget. Never below zero.
X-RateLimit-Reset	When your daily budget next frees a request, as a Unix timestamp in seconds. The per-minute burst cap has no header of its own. See Limits
Retry-Afteron a 429	Seconds to wait before retrying, from whichever limit refused the request. See Limits

Errors

The API returns these error status codes:

400
Malformed input: a bad parameter, an empty or over-100 bulk update, or a write that sets and clears the same field in one call.
401
No key, or one that doesn't parse. Send it as X-API-Key or as a bearer token.
402
A plan quota is in the way — today, that's category creation only. It's about what you're creating, not how fast you're calling, so waiting doesn't clear it and a bigger plan does. Calling too fast is a 429 instead.
403
The key doesn't carry the scope this call needs — or, on either transaction write, the id belongs to someone else or doesn't exist at all. The API doesn't tell those two apart.
404
An account that isn't there. Only the balance endpoint returns it: an accountGroupKey naming no account, or one that isn't shaped like a key at all, comes back 404 with no body. Transactions never 404 — see 403.
409
Something else changed the row while you were writing to it. Read it again and send your write again.
429
Too many requests. You've spent your daily budget or hit the per-minute burst cap. Retry-After says how long to wait, and unlike a 402, waiting clears it. See Limits for which limit refused and the per-plan figures.

Error shapes

Most errors come back in the same shape — statusCode, message, and an errors object naming what was wrong. Not all of them: a 401 and a 404 come back with no body at all, so read the status before you read the body.

Example

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

Request ID

Every response carries a fly-request-id header. Include it when you contact support about a specific request.

cURL

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

cURL (write call)

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

Common errors

Setting a field and clearing it in the same write — 400.
More than 100 ids in a bulk update — 400, and nothing is changed. Fewer than one is the same.
A transaction that isn't yours, or isn't there at all — 403, never 404. So the response never tells you whether an id exists, only that it isn't yours to see.
Someone or something else changed the row first — 409.

Limits

Two of the ten documented endpoints cap how much you can ask for in one call. The other eight don't.

That doesn't mean unlimited: keys still expire, writes still have field-length limits, creating a category can meet a plan quota, and your plan can still hide older history. None of this is a rate limit — see below.

Accounts, balance, summary, the category and tag lists, creating a category, creating a tag, and the single-transaction write have no per-call volume cap. You get the whole set back, or the one row you named.
pageSize is clamped to 100, not refused. Ask for more and you get 100 rows back with a 200 — read pagination.pageSize in the response rather than trusting what you sent.
The bulk transaction write is capped at 100 ids, and unlike pageSize it's refused rather than clamped: send 101 and you get a 400 and nothing changes.
Keys expire on a schedule you choose at creation — up to 90 days on the free plan, 365 on a paid one. There's no never-expires option.
Your plan can apply a history-window floor that hides older transactions. The transactions response carries the historyWindow fields that tell you whether one applied and where it fell.

Rate limits

Every plan can call this API, and every plan is metered. What counts: the calls you make with a key. Two limits run at once — a daily budget and a per-minute burst cap — and going over either one comes back 429.

Your daily budget belongs to you, not to a key. Every REST key on your account draws on the same daily budget, so minting a second key doesn't buy you more calls. MCP tool calls are metered separately: spending one never spends the other.

Requests per day and per minute, by plan
Plan	Per day	Per minute
Basic	250	30
Organize	1,000	30
Automate	10,000	60
Operate	25,000	120

When Era meters a call, the response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. All three describe your daily budget, which rolls over 24 hours rather than resetting at midnight: requests come back one at a time as your oldest calls turn 24 hours old. The per-minute burst cap has no header, so pace against the figure in the table yourself. Remaining can read well above zero while a burst still comes back 429. If Era can't measure your usage, it serves the call and sends no rate-limit headers, so treat missing headers as a missing reading, not an error.

What a 429 tells you

A problem-details body. Its detail field is plain text, not structured fields: it names the limit you hit, what that limit allows, when your next request frees up, and the plan that raises it, or that you're already on the highest. Don't parse it. To branch in code, read the headers: Remaining at 0 means the daily budget refused, and above 0 means the per-minute burst cap did.

429 response

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

A 429 also carries Retry-After, a whole number of seconds measured from whichever limit refused: up to a minute for the per-minute burst cap, up to 24 hours for the daily budget. A refused call spends nothing, so retrying early costs you nothing, but it comes back 429 again. When Retry-After elapses, one request frees up, not the whole budget. Send it, then read the headers or the next Retry-After.

None of this protects a key you've lost track of. A leaked key spends your budget exactly the way you would. If you're unsure about one, revoke it. See Security and key handling below.

See what each plan includes

Conventions

Response fields are camelCase. Query parameters are case-insensitive, so camelCase works there too — the published spec spells them PascalCase, which is why you'll see both forms around.

A field naming a calendar day is YYYY-MM-DD. A field naming an instant is ISO 8601 with an offset.

Paging sizes are clamped, not refused. Ask for a pageSize of 500 and you get 100 rows and a 200, not an error — so read pagination.pageSize back rather than trusting what you sent.

A response can carry fields this page doesn't list. Ignore the ones you don't recognize rather than failing on them — that's what keeps your client working as the API grows.

REST is plain HTTP; there's no SDK to install. Any language with an HTTP client works.

Versioning and changes

Everything documented here is covered by this policy.

There's no version number in the path and no version header. Each endpoint has one live version, and it's the one documented here.

What we may change without notice

None of these break a client that follows the conventions above.

Add an endpoint, or an operation on an existing one.
Add a field to a response.
Add an optional parameter. Leave it out and nothing changes.
Add a value to a fixed set, like a status or a type.
Add a response header.

What we won't change without notice

Any of these can break a working client.

Remove an endpoint, or change its path or method.
Remove or rename a response field.
Change a field's type or meaning.
Require a parameter that's optional today.
Reject input that's accepted today.
Change the scope an endpoint needs.

Before any of those, the changelog says so at least 90 days ahead and tells you what to change. What works today keeps working until then.

Changes are announced on the changelog, linked in the Changelog section below. There's no email or feed yet, so check it when you're planning work against the API.

While the API is in beta, the documented set will keep growing. What's already here won't break you without warning.

Changelog

Updates to the Era Developer Platform, including the Era API, newest first. The policy above says what gets warning and how much; the changelog is where those warnings appear.

Open the changelog

Security and key handling

Approving an agent creates a key

When you approve an agent over OAuth, Era makes an API key for it. It lands in the same dashboard list as the ones you make yourself, under a name Era generates from the client's own name.

How it's named

Auto -- Claude

It carries exactly the scopes you approved on that screen, and nothing else. Revoke it from the dashboard and the agent can't get new access until you approve it again. A token it already has keeps working until it expires, at most an hour.

Writes show up in your activity log, reads don't

Making and revoking a key both show up in your activity log, and so does every tool call an agent makes over MCP. A REST write shows up too — as the change it made, like a tag created or a transaction edited. A REST read adds no entry at all. Era records these entries on every plan, but reading the full log takes Organize or higher — below that you see only the most recent ones. Even on a write, REST keeps no per-request log: what's recorded is the change, not the call, and the entry lands under your account rather than the key that made it.

If you're ever unsure about a key, revoke it. A key you made yourself stops working on REST and MCP from its next request. An agent's key stops getting new access right away, and any token it already has expires within an hour. Making a replacement takes a minute.

More to know before you rely on a key.
Fact	What it means
Scopes are coarse	banking:read reads more than the six on this page — the same scope covers the rest of your account's reads too: balances, holdings, connections, spending. One scope, no narrower option. Write scopes are on the menu too, same as reads — so treat any key like a password. It acts as your account, not a slice of it. banking:write can change categories, tags, and transaction metadata, manage manual accounts and balances, and connect or disconnect institutions — no scope on this page can move money between your bank accounts.
Scopes don't update	A key's scopes are fixed when you make it and never change afterwards. That matters for anything a scope covers that isn't switched on yet: grant social:write today and the key still has it when shared views arrive. Grant what you're using now, not what you might use later.
No approval needed	You're already signed in to your own account, so making a key needs nobody else's sign-off — there's no review and no waiting list, and nobody at Era approves the request. It's written to your activity log the moment you make it, so an unfamiliar key is easy to spot.
Bank login stays out of reach	A key can't reach your bank login, because Era never has it. You enter it in the connection flow run by the data provider, not on an Era screen — what Era keeps afterwards is a per-connection access token, encrypted at rest with AES-256, that you can throw away by disconnecting the institution.
Keys are hashed, not stored	Your key is 256 bits of random data, hashed with SHA-256 before it's stored. We keep the hash, not the key. Lose it, revoke it, and make a new one.

How Era secures your data

Core resources

Accounts

GET/banking/accounts

Scope required

banking:read

Every account you can see, across every connected institution, with the count of the ones left out beside them. Each account carries its accountGroupKey — the value the balance endpoint takes in its path — and the connectionId it belongs to, so this is the call to make first. Takes connectionId to narrow to a single connection, and includeExcluded to bring in accounts you've hidden.

Query parameters
connectionIdoptional	Narrow the list to one connection's accounts.
includeExcludedoptional	Include tier-excluded and hidden accounts too, with their balances obfuscated. Defaults to false.

Response · 200

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

On an account you've hidden or your plan excludes, the balance fields come back null rather than zero — null means withheld, not empty. supportsTransactions is null in the same spirit: it means Era can't say, and never that the answer is no.

Account balance

GET/banking/accounts/{accountId}/balance

Scope required

banking:read

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.

Response · 200

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

A hidden account, or one whose connection was severed, still answers 200 — with the balance fields null. A 404 means the account genuinely isn't there, or the key wasn't shaped like one. Watch the visibility field here: it's null when the account is visible, and a string such as tier_excluded when it isn't.

Account summary

GET/banking/accounts/summary

Scope required

banking:read

Totals across the accounts you can see: totalAssets, totalLiabilities, and netWorthHint, which is the first minus the second. Takes no parameters.

Response · 200

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

netWorthHint counts only the accounts in this response, so totalHiddenCount tells you what it's missing. Treat it as a starting figure rather than an authoritative net worth.

Transactions

GET/banking/transactions

Scope required

banking:read

Your transactions, a page at a time, wrapped in an envelope with the paging counts beside them. Takes page and pageSize (100 is the ceiling), plus optional filters for account, date range, applied rules, and assigned tags.

Query parameters
accountIdoptional	Narrow to one account's transactions, by its accountGroupKey.
fromDateoptional	Only transactions on or after this date.
toDateoptional	Only transactions on or before this date.
pageoptional	Page number, 1-indexed. Defaults to 1.
pageSizeoptional	Rows per page. Defaults to 50, clamped to 100.
sortByoptional	Field to sort by: transactionDate, amount, description, category, or merchantName.
sortDirectionoptional	asc or desc. Defaults to descending.
categoryKeysoptional	Only transactions in these categories, by their fcat_ keys. Takes a list, not a single key, and a transaction matches if its effective category is any one of them. Send the literal "uncategorized" to select the transactions that have no category at all.
searchoptional	Full-text search across merchant, description, category, account name, and amount.
ruleIdsoptional	Only transactions an automation rule touched, by the rule's key.
tagKeysoptional	Only transactions carrying one of these tags.
reviewStatusesoptional	needs_review, reviewed, or flagged. Takes a list; a transaction matches if its review status is any one of them.
includeChildrenoptional	With a category filter set, also include transactions in the subcategories of every key you passed. Defaults to false.
includePendingoptional	Also return pending charges from the last 7 days, marked isPending. Defaults to false. Pending rows are read-only.

Response · 200

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

Your plan may apply a history-window floor, which hides transactions older than it. That's why the response carries the historyWindow fields: historyWindowApplied tells you a floor actually hid something, historyWindowFloorDate is where it fell, historyWindowHiddenCount is how many rows are behind it, and historyWindowEarliestDate is how far your history really goes. Without them a short result set is indistinguishable from an account with no older transactions. Two of them change what you write: historyWindowHiddenCount can be null even when a floor applied, so read null as unknown rather than zero; and when historyWindowDegraded is true, Era couldn't confirm your plan on that read, so the floor date is a guess rather than a fact. On a confirmed paid read no floor applies and historyWindowApplied comes back false.

Your plan also sets how many requests a day you get, and this API enforces it. The per-plan figures, the headers every response carries, and what a 429 tells you are all in Limits.

See what each plan includes

Change one transaction

Four things on a transaction are yours to override: its category, the merchant name, a note of your own, and its review status. Send only the ones you're changing — anything you leave out stays as it is. The id in the path is the transaction's utgr_ key. Mutating, so it needs banking:write rather than banking:read.

PUT/banking/transactions/{id}

Scope required

banking:write

Request body
categoryKeyoptional	The fcat_ key of the category to assign. Leave it out and the transaction keeps the category it has.
merchantNameoptional	A merchant name of your own, up to 1000 characters. Leave it out and the current name stays.
descriptionoptional	A note of your own on this transaction, up to 5000 characters. Leave it out and the current note stays.
clearCategoryoptional	Drops your category override, so Era's own categorization takes over again. Defaults to false.
clearMerchantNameoptional	Drops your merchant-name override, so the name your bank sent comes back. Defaults to false.
clearDescriptionoptional	Drops your description override, so the description your bank sent comes back. Defaults to false.
reviewStatusoptional	Mark it needs_review, reviewed, or flagged.
clearReviewStatusoptional	Drops your review-status override. Defaults to false.

Response · 200

{
  "transaction": { … }
}

You get the whole updated transaction back, in the same shape the list above returns — not reprinted here, because it's a large object that's still moving. Setting a field and clearing it in the same call comes back 400. A transaction that isn't yours, or isn't there at all, comes back 403 — the API doesn't tell those two apart. And if something else changed the same row while you were writing, you get 409: read it again and send it again.

Change up to 100 at once

The same four overrides, applied to a list of transactions in one call. Every id in the list gets the same changes — there is no per-transaction variation. Mutating, so it needs banking:write rather than banking:read.

PUT/banking/transactions/bulk

Scope required

banking:write

Request body
transactionIds	The utgr_ keys of the transactions to change. At least one, and no more than 100. Over 100 is refused rather than trimmed — unlike pageSize above, you get a 400 and nothing changes at all.
categoryKeyoptional	The fcat_ key of the category to assign. Leave it out and the transaction keeps the category it has.
merchantNameoptional	A merchant name of your own, up to 1000 characters. Leave it out and the current name stays.
descriptionoptional	A note of your own on this transaction, up to 5000 characters. Leave it out and the current note stays.
clearCategoryoptional	Drops your category override, so Era's own categorization takes over again. Defaults to false.
clearMerchantNameoptional	Drops your merchant-name override, so the name your bank sent comes back. Defaults to false.
clearDescriptionoptional	Drops your description override, so the description your bank sent comes back. Defaults to false.
reviewStatusoptional	Mark it needs_review, reviewed, or flagged.
clearReviewStatusoptional	Drops your review-status override. Defaults to false.

Response · 200

{
  "transactions": [ … ]
}

You get the updated transactions back, in the same shape the list above returns. Setting a field and clearing it in the same call comes back 400, and so does an empty list. A list holding a transaction that isn't yours, or isn't there at all, comes back 403 for the whole call — nothing is changed. If something else changed one of those rows while you were writing, you get 409: read them again and send them again.

Add a category

A user-defined category under an existing parent. Mutating, so it needs banking:write rather than banking:read.

POST

Scope required

banking:write

Request body
slug	URL-safe identifier — lowercase letters, numbers, and hyphens, 2 to 50 characters.
parentCategoryKey	The fcat_ key of the category this one nests under.
name	Display name.
descriptionoptional	Optional description.
iconNameoptional	Optional icon name.
spendingTypeoptional	Optional spending classification.
displayOrderoptional	Optional sort position among its siblings.
assignmentEligibilityoptional	Optional rule for which transactions this category can be assigned to.
sourceSystemKeysoptional	Optional list of existing category keys whose transactions should be routed here going forward.
applyRetroactivelyoptional	When true, re-evaluates past transactions against the new routing too. Defaults to false.

Response · 201

{
  "categoryKey": "fcat_side_hustle_9f2a",
  "overlayProjectionKey": "fcov_9f2a1c",
  "action": "created",
  "isQuotaExceeded": false,
  "createdMappingRuleKeys": [ … ],
  …
}

The response also carries retroactiveAffectedCount, mergeSourcesHiddenCount, mergeSourcesTotalCount, and meterGate — fields this call shares with category merges and quota-limited creates, not shown here.

Query parameters
tagTypeoptional	Filter by tag origin: user, system, or auto.
includeDeletedoptional	Include deleted tags. Defaults to false.

Create a tag

A new tag, canonicalized to lowercase. Mutating, so it needs banking:write rather than banking:read. System tags cannot be created through the API; user and auto tags can.

POST

Scope required

banking:write

Request body
name	The tag's canonical name.
displayNameoptional	Optional display name. Defaults to the canonical name.
tagTypeoptional	user or auto. Defaults to user. system is refused — it is reserved for tags Era creates itself.
coloroptional	Optional hex color for display.
iconoptional	Optional icon name.

Response · 201

{
  "tag": {
    "tagKey": "utag_9c2f01ab",
    "name": "business-expense",
    "displayName": "Business expense",
    "tagType": "user",
    "version": 1,
    "createdAt": "2026-08-26T09:15:00Z"
  }
}

Era API

Quickstart

Available APIs

Authentication

Response headers

Errors

Error shapes

Request ID

Common errors

Limits

Rate limits

What a 429 tells you

Conventions

Versioning and changes

What we may change without notice

What we won't change without notice

Changelog

Security and key handling

Core resources

Accounts

Account balance

Account summary

Transactions

Change one transaction

Change up to 100 at once

Categories

Add a category

Tags

Create a tag