Client
FireflyClient owns an async HTTP client. Pass the Firefly III instance root
and a personal access token, then close it in a finally block. Read methods
return simplified domain models. Updates affect real data and may trigger
Firefly III rules and webhooks.
For an executable flow, start with Getting started. For skipped multipart groups and matching behavior, see Transactions and matching.
FireflyClient
Async client for the supported Firefly III endpoints.
Pass the instance root URL without /api/v1 and a personal access
token. Always call :meth:close when finished, typically in a finally
block. Listing methods return handwritten domain models; the generated
OpenAPI transport models remain internal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_url
|
str
|
Firefly III instance root, for example
|
required |
token
|
str
|
Personal access token sent as a bearer token. |
required |
close() -> None
async
Release the underlying HTTP connections.
Call this once after the final request. The client does not implement an async context manager.
get_about() -> SystemInfo
async
Read version and environment information from /api/v1/about.
Returns:
| Type | Description |
|---|---|
SystemInfo
|
System information. Individual fields may be |
SystemInfo
|
III omits them. |
Raises:
| Type | Description |
|---|---|
FireflyAPIError
|
The request fails or the response is invalid. |
fetch_transactions(*, tx_type: str = 'withdrawal', page_size: int = 1000, max_pages: int | None = None, start_date: date | None = None, end_date: date | None = None) -> list[SimplifiedTx]
async
Fetch single-split transactions across Firefly III pages.
Multipart groups and responses that cannot be mapped are logged and
skipped. The result is therefore not guaranteed to contain every
transaction group reported by Firefly III. Use
fetch_transactions_with_stats to count those skipped groups.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tx_type
|
str
|
Firefly III transaction type filter. Defaults to
|
'withdrawal'
|
page_size
|
int
|
Requested number of groups per API page. |
1000
|
max_pages
|
int | None
|
Maximum pages to request, or |
None
|
start_date
|
date | None
|
Inclusive start date sent to the API, if supplied. |
None
|
end_date
|
date | None
|
Inclusive end date sent to the API, if supplied. |
None
|
Returns:
| Type | Description |
|---|---|
list[SimplifiedTx]
|
Successfully mapped transactions in API order. |
Raises:
| Type | Description |
|---|---|
FireflyAPIError
|
A request fails or a page has an invalid schema. |
fetch_categories(limit: int = 1000, simplified: bool = False) -> list[SimplifiedCategory]
async
Fetch all categories across Firefly III pages.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
limit
|
int
|
Requested number of categories per API page. |
1000
|
simplified
|
bool
|
Retained for compatibility; currently ignored. The
method always returns |
False
|
Returns:
| Type | Description |
|---|---|
list[SimplifiedCategory]
|
Mapped categories in API order. |
Raises:
| Type | Description |
|---|---|
FireflyAPIError
|
A request fails or the response is invalid. |
get_transaction(transaction_id: int) -> SimplifiedTx
async
Fetch one single-split transaction by Firefly III group ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
transaction_id
|
int
|
Firefly III transaction group ID. |
required |
Returns:
| Type | Description |
|---|---|
SimplifiedTx
|
The mapped transaction. |
Raises:
| Type | Description |
|---|---|
FireflyAPIError
|
The request or validation fails, or the group has multiple splits or cannot be mapped. |
update_transaction(transaction_id: int, update: TransactionUpdate) -> SimplifiedTx
async
Update selected fields of a single-split transaction.
Firefly III rules and webhooks are enabled for this request. Supplying
tags replaces the full tag list; use build_add_tag_payload to
preserve existing tags while adding one. The returned response must
still be mappable as a single-split transaction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
transaction_id
|
int
|
Firefly III transaction group ID. |
required |
update
|
TransactionUpdate
|
Non-empty selection of description, notes, tags, and/or category ID. |
required |
Returns:
| Type | Description |
|---|---|
SimplifiedTx
|
The mapped transaction returned by Firefly III after the update. |
Raises:
| Type | Description |
|---|---|
ValueError
|
No update field was supplied. |
FireflyAPIError
|
The request or validation fails, or the returned transaction cannot be mapped. |
TransactionUpdate
dataclass
Fields accepted by FireflyClient.update_transaction().
Supply at least one field. None means leave a field unchanged; an
empty tag list removes all tags. A supplied tag list replaces the entire
existing list rather than adding to it.
Attributes:
| Name | Type | Description |
|---|---|---|
description |
str | None
|
Replacement description. |
notes |
str | None
|
Replacement notes; an empty string clears existing notes. |
tags |
list[str] | None
|
Complete replacement list of tag names. |
category_id |
int | None
|
Firefly III category ID to assign. |
FireflyAPIError
Bases: RuntimeError
Error raised for HTTP, network, JSON, or response mapping failures.
Attributes:
| Name | Type | Description |
|---|---|---|
status_code |
HTTP status for an HTTP or JSON response error, or
|