FireflyIIINet 6.7.8.3
dotnet add package FireflyIIINet --version 6.7.8.3
NuGet\Install-Package FireflyIIINet -Version 6.7.8.3
<PackageReference Include="FireflyIIINet" Version="6.7.8.3" />
<PackageVersion Include="FireflyIIINet" Version="6.7.8.3" />
<PackageReference Include="FireflyIIINet" />
paket add FireflyIIINet --version 6.7.8.3
#r "nuget: FireflyIIINet, 6.7.8.3"
#:package FireflyIIINet@6.7.8.3
#addin nuget:?package=FireflyIIINet&version=6.7.8.3
#tool nuget:?package=FireflyIIINet&version=6.7.8.3
FireflyIIINet - the C# library for the Firefly III API
This is a .NET client for the Firefly III personal finance manager API.
This C# SDK is a hand-maintained client for the Firefly III API, built on Refit and System.Text.Json. It is kept in sync with the Firefly III OpenAPI specification manually — updates are applied directly to the source.
- API version: 6.7.8 (v1 endpoints, plus the two v2 endpoints last documented in 6.2.21)
- SDK version: 6.7.8.3 (tracks the API version; a 4th revision component denotes client-only changes)
- Source specification: api/firefly-iii-v6.7.8-v1.yaml (upstream stopped publishing v2 specs after 6.2.21)
- All released specifications (0.10.4 – 6.7.8): api/
Rule triggers and actions go beyond the specification. The spec's
RuleTriggerKeywordenum lists 36 values, but Firefly III accepts every search operator as a rule trigger (config/search.php, 144 of them) and returns them verbatim fromGET /rules; the same applies toRuleActionKeyword(config/firefly.php). Both enums therefore carry the server's full set, and an unrecognised value deserializes toUnknowninstead of failing the response. Don't writeUnknownback to the API — a rule read with an unknown keyword cannot be round-tripped.
Frameworks supported
- .NET 10.0
- .NET Framework 4.8
Dependencies
- Refit - 15.0.0 or later
- Refit.Reflection - version-locked to Refit (keeps
RestService.For<T>working on all targets) - System.Text.Json - 10.0.10 or later
- System.ComponentModel.Annotations - 5.0.0 or later
Installation
Build with dotnet build FireflyIIINet.sln, then reference the library and use the namespaces:
using FireflyIIINet.Api; // the Refit interfaces (IAccountsApi, ITransactionsApi, ...)
using FireflyIIINet.Client; // FireflyRefitSettings, SerializerOptions
using FireflyIIINet.Model;
using Refit;
This client is a set of Refit interfaces — one per API area
(IAboutApi, IAccountsApi, IAttachmentsApi, IAutocompleteApi, IAvailableBudgetsApi,
IBillsApi, IBudgetsApi, ICategoriesApi, IChartsApi, IConfigurationApi, ICurrenciesApi,
IDataApi, IInsightApi, ILinksApi, INetWorthApi, IObjectGroupsApi, IPiggyBanksApi,
IPreferencesApi, IRecurrencesApi, IRuleGroupsApi, IRulesApi, ISearchApi, ISummaryApi,
ITagsApi, ITransactionsApi, ITransactionsSumApi, IUsersApi, IWebhooksApi).
You build a client with an HttpClient plus the settings from FireflyRefitSettings.Create(),
which wire up the library's System.Text.Json options and the URL parameter formatting the
Firefly III API expects (lowercase booleans, [EnumMember] enum values, yyyy-MM-dd dates).
Auth is a personal access token supplied as a bearer token on the HttpClient.
Getting Started
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using FireflyIIINet.Api;
using FireflyIIINet.Client;
using FireflyIIINet.Model;
using Refit;
var http = new HttpClient { BaseAddress = new Uri("https://demo.firefly-iii.org/api") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<personal access token>");
var accounts = RestService.For<IAccountsApi>(http, FireflyRefitSettings.Create());
var list = await accounts.ListAccount(type: AccountTypeFilter.Asset);
foreach (var account in list.Data)
Console.WriteLine($"{account.Id}: {account.Attributes.Name}");
A runnable end-to-end example (create + delete a transaction) lives in src/Example/.
Servers behind Cloudflare need a
User-Agent.HttpClientsends none by default, and Cloudflare's bot protection answers such requests with 403 before they reach Firefly III. The public demo (https://demo.firefly-iii.org) is one of them. Add one to the client:http.DefaultRequestHeaders.UserAgent.ParseAdd("MyApp/1.0");.No native AOT. The SDK uses reflection-based System.Text.Json and Refit's reflection request builder, so it does not work in an app published with native AOT, or with
JsonSerializerIsReflectionEnabledByDefaultoff: every response fails to deserialize. A .NET 10 file-based app turns AOT on by default; add#:property PublishAot=false.
Errors
Refit throws Refit.ApiException for non-success status codes; the JSON error payload is
available via ex.Content and can be deserialized to the spec's error models
(ValidationError, NotFound, Unauthenticated, ...) with SerializerOptions.Default.
Notes
Transaction/TransactionSplitStorepiggy bank properties intentionally serialize explicitnullvalues (piggy_bank_id,piggy_bank_name) — the API distinguishes absent from null.Chart data sets (
ChartDataSet,ChartDataSetV2) carryentriesas the server sends them, an object of label to value, which the spec mis-declares as an object withitems.ChartEntriesConverterreads it (and PHP's[]for an empty set) into a list of points in the server's order, each withKeyandValue.Optional inputs are nullable: Refit parameters that default to
null, model constructor parameters that are not required, and[AllowNull]on optional model properties, so a nullable-enabled consumer can pass and assignnull("leave unset") without warnings. The library itself compiles with<Nullable>annotations</Nullable>; getters keep their declared types, so reading an optional field still needs the caller's own null check.Fields the spec marks both required and
nullable: true(a piggy bank'starget_amount, a recurrence'srepeat_until, a rule action'svalue, ...) takenullin their constructors and always send the key,nullincluded.A request sends only what the caller set. Optional fields left unset are not sent, rather than as
nullor0001-01-01, which the server rejects (AccountStorewithout a currency failed with "The currency id must be a number."). On the*Updatemodels theboolandintfields arebool?/int?and are left out while null, so an update changes only what was set: a rename used to sendactive: false, deactivating a budget, bill, recurrence, rule group or webhook. On the*Storemodelsactivedefaults totrue, an unsetorder(0) is left for the server to assign, and a recurrence repetition'sweekenddefaults to1.Some updates need more than the spec requires:
CategoryUpdateneedsName,RecurrenceUpdateneedsTransactions,TransactionLinkUpdateneedsLinkTypeId,InwardIdandOutwardId, and aTransactionUpdateof a group with more than one split needsGroupTitle, even when the title is unchanged. Without them the server answers 500 or 422.A category's
Coloris six hex digits without#("336699"); the server rejects"#336699".The server sends a group's splits in its own order, not the order they were stored in; find a split by its
TransactionJournalId, not its position.Piggy banks follow the server where the spec differs:
PiggyBankAccountStore.Idis sent asaccount_id, andPiggyBankStore/PiggyBankUpdatehaveTransactionCurrencyIdandTransactionCurrencyCode(one of them is required on create), which the spec leaves out.Responses are read as the server sends them: a
stringproperty also accepts a JSON number (an available budget'sspent_in_budgets[].currency_idis1), a date-only field also accepts a date-time (a recurrence'sfirst_date), and a budget without a currency of its own has a nullCurrencyDecimalPlaces.ConfigValueFilter, thetitleof eachGET /v1/configurationentry, carries the editableconfiguration.*settings the spec lists only onConfigValueUpdateFilter, andconfiguration.enable_batch_processing, which the spec lists nowhere. Without them the whole list failed to deserialize. An unrecognised title reads asUnknown, as with rule keywords; don't send it back. Checked against a live 6.7.9: all 33 settings read.IDataApi.DestroyData'sunusedis abool?: the spec types it as an int64 array, but the server validates it astrue/false.GET /v1/release-notes/{version}has two methods:GetReleaseNotes(version), andGetCurrentReleaseNotes()for the server's own version (the route makes{version}optional). The model'srelease_notesfield isReleaseNotesHtml, since a member cannot share theReleaseNotestype's name.To remove a stored value, clear the field:
update.Clear(u => u.TargetDate)sets it to null and sends"target_date": null, where a null left on the model is not sent at all and the server keeps what it had. A value assigned afterwards is sent instead. Checked against a live 6.7.9 (scripts/clear-check.cs), the server clears on null: an account's IBAN, BIC, account number and opening balance and its date; a category's notes and colour; a piggy bank's target amount and date; a tag's date and location; a recurrence'srepeat_untilandnr_of_repetitions, and its transaction's budget and category; a split's internal reference, external URL and six optional dates. Some fields need something other than null:- A split's foreign amount goes with
ForeignAmount = "0", which removes the foreign currency too; null leaves both. - A bill's group goes with
ObjectGroupTitle = ""(orObjectGroupId = 0); null is rejected. - A credit card's
MonthlyPaymentDatestays while the account is a credit card; it is dropped when the update also changesAccountRoleaway fromccAsset.
And some cannot be removed through the API at all: a bill's
EndDateandExtensionDate(null and""are both rejected) and a piggy bank's group (an empty title is rejected,ObjectGroupId = 0is accepted but changes nothing).- A split's foreign amount goes with
RuleTriggerUpdate.Prohibited(the "NOT" of a trigger) is sent on update too, although the spec lists it onRuleTriggerStoreonly.CategoryUpdate.NotesandCategoryUpdate.Colorare three-state, as the server treats them: never assigned (or null in the constructor) leaves the key out and the stored value unchanged; assigningnullsendsnulland clears it; assigning a value sets it.The other updates (
AccountUpdate,BillUpdate,BudgetUpdate,BudgetLimitUpdate,PiggyBankUpdate,RecurrenceUpdate,TransactionSplitUpdate) leavenotesout whenNotesis null, which keeps the stored notes; assign""to clear them.TransactionLinkUpdateis the exception: the server removes a link's notes when the key is left out, so send the current notes again to keep them. (Attachments could not be checked against the demo.)Date-only fields are written as
yyyy-MM-ddviaOpenAPIDateConverter; date-time fields use RFC 3339.The test suite never hits the network — Refit slice tests use a capturing handler that records the outgoing request and returns canned JSON.
Development
There is no code generator in this repo. When the spec changes, edit the Refit interfaces under
src/FireflyIIINet/Api and the models under src/FireflyIIINet/Model directly, and keep
the spec copy under api/ in sync.
dotnet build FireflyIIINet.sln
dotnet test FireflyIIINet.sln
# Check whether upstream has published API specs not yet vendored in api/,
# and (--diff) how far the pinned SDK spec is behind the newest upstream v1.
# This is a .NET 10 file-based app (needs the .NET 10 SDK; the library targets net8.0).
# Upstream publishes one branch per release, so the check scans every branch (~22 GitHub API
# requests); set GITHUB_TOKEN or GH_TOKEN to stay clear of the 60/h anonymous limit.
dotnet run scripts/check-spec-version.cs -- --diff
# Read-only live smoke test against a real server (GETs only): the 6.7.x additions and every
# top-level list (features the server has switched off are skipped). Works against the public demo,
# https://demo.firefly-iii.org (demo@firefly-iii.org / demo): create a personal access token
# under Options > Profile > OAuth.
FIREFLY_TOKEN=<token> dotnet run scripts/smoke-test.cs -- https://demo.firefly-iii.org
# Live check that the server clears each field an update sends as null (ClearedFields.Clear).
# It writes (creates, clears and deletes its own objects), so it runs against a demo server only:
# the URL defaults to the public demo, and it refuses a token whose user's email isn't demo@...
FIREFLY_TOKEN=<token> dotnet run scripts/clear-check.cs [-- <demo server url>]
A scheduled workflow (spec-check.yml) runs the same check weekly (without --diff); when
new upstream specs appear it opens a spec-check-labeled issue, comments on that issue on
later runs while they stay unvendored, and closes it once api/ is complete again.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Framework | net48 is compatible. net481 was computed. |
-
.NETFramework 4.8
- Refit (>= 15.0.0)
- Refit.Reflection (>= 15.0.0)
- System.ComponentModel.Annotations (>= 5.0.0)
- System.Text.Json (>= 10.0.10)
-
net10.0
- Refit (>= 15.0.0)
- Refit.Reflection (>= 15.0.0)
- System.ComponentModel.Annotations (>= 5.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 6.7.8.3 | 91 | 11/7/2026 |
| 6.7.8.2 | 97 | 11/5/2026 |
| 6.7.8.1 | 127 | 10/13/2026 |
| 6.7.8 | 103 | 10/12/2026 |
| 6.7.2.1 | 101 | 10/12/2026 |
| 6.7.2 | 125 | 9/16/2026 |
| 6.7.1 | 117 | 9/16/2026 |
| 6.7.0 | 121 | 9/16/2026 |
| 6.6.6.2 | 153 | 8/15/2026 |
| 6.6.6.1 | 131 | 8/15/2026 |
| 6.6.6 | 137 | 8/12/2026 |
| 6.6.2 | 140 | 8/12/2026 |
| 6.5.5 | 140 | 8/12/2026 |
| 6.5.1 | 144 | 8/12/2026 |
| 6.4.17 | 139 | 8/12/2026 |
| 6.4.16 | 132 | 8/12/2026 |
| 6.4.14 | 136 | 8/12/2026 |
| 6.4.8 | 127 | 8/12/2026 |
| 6.4.4 | 131 | 8/12/2026 |
| 6.4.3 | 130 | 8/12/2026 |
6.7.8.3, client-only fixes against Firefly III API 6.7.8, checked against a live 6.7.9. GetConfiguration no longer fails: ConfigValueFilter gains the seven configuration.* settings the server returns and the spec lists only for updates, or not at all (enable_exchange_rates, use_running_balance, enable_external_map, enable_external_rates, allow_webhooks, enable_batch_processing, valid_url_protocols), and reads an unrecognised title as Unknown instead of failing the whole list. The README now lists what the server clears on null and what needs another value: a split's foreign amount goes with "0", a bill's group with "", a credit card's payment date only with a role change; a bill's end and extension dates and a piggy bank's group cannot be removed. An update of a group with several splits needs GroupTitle. 6.7.8.2: ClearedFields.Clear (update.Clear(u => u.TargetDate)) sends a field as null so the server removes it; BillUpdate.EndDate and ExtensionDate are DateTime?; RuleTriggerUpdate gains Prohibited, which the spec leaves out. 6.7.8.1: requests send only what the caller set; the bool/int fields of the *Update models are bool?/int?; *Store active defaults to true; piggy banks send account_id and a currency; responses read numbers as strings, date-times as dates and a null budget CurrencyDecimalPlaces; CategoryUpdate.Notes and Color are three-state.