data:read (connections and consents need connections:read). Banking reads may pass through the short-lived connection gateway cache; live banking and brokerage provider payloads are never written to Redbark’s primary database or logs. Opt-in Documents stores uploaded files and extracted transactions separately. See Caching for freshness, purge, and opt-out behaviour.
Connections
GET /v2/connections (cheap), GET /v2/connections/{id}. Filters: status[], provider. Include: accounts.
status is computed: pending (accounts not landed yet or MFA outstanding), active, expiring (consent ends within 30 days), expired, invalidated (bank-side), revoked.
Consents
GET /v2/consents?connection= and GET /v2/consents/{id}. status is active, expiring, expired or withdrawn; brokerage consents have no expiry (expires_at: null). termination_reason is free text, not an enum: it is either our own note for a withdrawal we initiated (connection_deleted) or the bank’s wording for one the user made at their end. Show it, do not branch on it.
Accounts
GET /v2/accounts?connection= (cheap), GET /v2/accounts/{id}. account_number is masked to the last four digits.
status is available, syncing (first transactions still arriving) or unavailable.
An account the provider stopped returning, for example a closed account or one removed from the consent, stays listed with
status: "unavailable". Its transactions, single-account balance, details, holdings and trades return 404 account_unavailable. Skip it rather than retrying; it becomes available again if the provider returns it. Bulk balances return an unavailable entry instead.GET /v2/accounts/{id}/balance(mid):{ "object": "balance", "account": "acct_…", "current": { "amount": 123456, "currency": "aud" }, "available": { "amount": 120000, "currency": "aud" }, "currency": "aud" };current/availableare money objects or null.GET /v2/balances?account=acct_…&account=acct_…(mid): reads up to 100 banking-account balances in one non-paginated response. Duplicate ids collapse and results retain the first-request order. Every account must exist, belong to you, and be a banking account; otherwise the whole request fails.GET /v2/accounts/{id}/details(mid): product name, deposit and lending rates, fees, features and loan details as the bank reports them, in snake_case. Australian Fiskil accounts only. Plaid and Akahu return400 not_supported; brokerage and Documents return400 wrong_endpoint_for_category.
observed_at (ISO timestamp or null) and freshness (fresh, stale, unavailable, or null for providers without freshness metadata). Fiskil observations are fresh for 4 hours. During transient failures or cooldowns, a live observation under 24 hours old may be returned with freshness: "stale"; its timestamp does not change. Unavailable balances remain null. When Redbark caching is disabled, Fiskil live balance attempts are serialized per connection and limited to once per account every 15 minutes. On GET /v2/balances, an account inside that limit is returned with freshness: "unavailable", null balances and retry_after_seconds, and the other accounts are returned normally. An account can also come back unavailable with retry_after_seconds when the request ran out of time before reaching it, or its connection is in a cooldown, deferred or temporarily unreachable; a client should merge results across calls. GET /v2/accounts/{account}/balance returns 429 balance_refresh_limited with Retry-After for its one account. Opt-out and authorisation/consent failures never use stale fallback.
Bulk balances retain successful providers’ results when another provider is deferred, times out or is unreachable. Retryable gaps include
retry_after_seconds; definitive provider rejections and provider-removed accounts do not. If every attempted provider fails, the request fails. Invalid, foreign and non-banking account ids still reject the whole request.freshness and null values before treating a total as complete. If the deferred connection has no balance to return, the request can fail with provider_wait; follow Retry-After. Plaid balances are not cached by Redbark and reflect Plaid’s last successful connection update, not a real-time bank refresh.
Transactions
GET /v2/transactions?account=acct_…&from=&to=&include_pending=true (heavy). account is required. Newest first, limit up to 100, follow next_page_url. Omitting from limits results to the last 30 days; pass it explicitly for older history, including imported Documents rows. A bare YYYY-MM-DD is an inclusive calendar boundary in your Redbark timezone, matching the returned date field. An RFC 3339 value is an instant and is converted to that timezone before the purchase-date filter is applied. When the 5,000 row ceiling is reached the response carries X-Redbark-Truncated: true; narrow from/to.
provider_category is the bank or enrichment code (see /v2/provider_categories); category is the user category it resolves to through your source claims, or null.
amount.currency is the transaction’s own currency, which can differ from the account’s currency. A PayPal or multi-currency account can return USD rows on an AUD account, for example. When the provider gives no currency for a transaction, amount.currency falls back to the account currency. Documents transactions use each extracted row’s currency the same way. Amounts are never converted between currencies. This applies to both list and single-transaction reads.reference is the provider-supplied payment reference. extended_description is additional transaction text, such as an NPP payment description or payer/payee label. Both fields are always present and are null when unavailable; availability depends on the bank and transaction. Use them alongside the amount and date for reconciliation, not as guaranteed unique identifiers.
GET /v2/transactions/{id}?account= retrieves one transaction by its tagged provider id within the account’s recent window (from/to optional, default last 30 days). If the id came from older history, pass dates covering it. The search reads at most 5,000 provider rows within a bounded page budget: 400 transaction_search_incomplete means narrow the window and retry, not that the transaction is absent. 404 transaction_not_found means the valid window was exhausted without a match; its message names that window.
Holdings and trades
GET /v2/holdings?account= and GET /v2/trades?account=&from=&to= (heavy, Professional plan). Quantities are decimal strings; prices and values are money objects in the holding’s currency.
One holding represents one instrument. If a broker reports several rows for the same instrument, such as staked and unstaked units, the top-level quantity, average price, market value, and unrealised P&L aggregate those rows. current_price comes from the largest position rather than being combined. positions preserves the individual rows, ordered by quantity descending, and instrument_id identifies the shared instrument. When the broker reports one row, positions contains one entry. If the provider omits an average price, market value, or unrealised P&L from any row, the corresponding aggregate is null rather than a partial total.
Provider categories
GET /v2/provider_categories lists every primary category and subcategory (with parent). This is what v1 served at /v1/categories; your own taxonomy lives at /v2/categories. The vocabulary is fixed and short, so this list is not paginated: it always returns every code in one response, next_page_url is always null, and limit is ignored.