FireflyIIINet 6.7.8.3

dotnet add package FireflyIIINet --version 6.7.8.3
                    
NuGet\Install-Package FireflyIIINet -Version 6.7.8.3
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="FireflyIIINet" Version="6.7.8.3" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="FireflyIIINet" Version="6.7.8.3" />
                    
Directory.Packages.props
<PackageReference Include="FireflyIIINet" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add FireflyIIINet --version 6.7.8.3
                    
#r "nuget: FireflyIIINet, 6.7.8.3"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package FireflyIIINet@6.7.8.3
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=FireflyIIINet&version=6.7.8.3
                    
Install as a Cake Addin
#tool nuget:?package=FireflyIIINet&version=6.7.8.3
                    
Install as a Cake Tool

FireflyIIINet - the C# library for the Firefly III API

CI NuGet

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 RuleTriggerKeyword enum lists 36 values, but Firefly III accepts every search operator as a rule trigger (config/search.php, 144 of them) and returns them verbatim from GET /rules; the same applies to RuleActionKeyword (config/firefly.php). Both enums therefore carry the server's full set, and an unrecognised value deserializes to Unknown instead of failing the response. Don't write Unknown back to the API — a rule read with an unknown keyword cannot be round-tripped.

Frameworks supported

  • .NET 10.0
  • .NET Framework 4.8

Dependencies

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. HttpClient sends 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 JsonSerializerIsReflectionEnabledByDefault off: 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/TransactionSplitStore piggy bank properties intentionally serialize explicit null values (piggy_bank_id, piggy_bank_name) — the API distinguishes absent from null.

  • Chart data sets (ChartDataSet, ChartDataSetV2) carry entries as the server sends them, an object of label to value, which the spec mis-declares as an object with items. ChartEntriesConverter reads it (and PHP's [] for an empty set) into a list of points in the server's order, each with Key and Value.

  • 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 assign null ("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's target_amount, a recurrence's repeat_until, a rule action's value, ...) take null in their constructors and always send the key, null included.

  • A request sends only what the caller set. Optional fields left unset are not sent, rather than as null or 0001-01-01, which the server rejects (AccountStore without a currency failed with "The currency id must be a number."). On the *Update models the bool and int fields are bool?/int? and are left out while null, so an update changes only what was set: a rename used to send active: false, deactivating a budget, bill, recurrence, rule group or webhook. On the *Store models active defaults to true, an unset order (0) is left for the server to assign, and a recurrence repetition's weekend defaults to 1.

  • Some updates need more than the spec requires: CategoryUpdate needs Name, RecurrenceUpdate needs Transactions, TransactionLinkUpdate needs LinkTypeId, InwardId and OutwardId, and a TransactionUpdate of a group with more than one split needs GroupTitle, even when the title is unchanged. Without them the server answers 500 or 422.

  • A category's Color is 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.Id is sent as account_id, and PiggyBankStore/PiggyBankUpdate have TransactionCurrencyId and TransactionCurrencyCode (one of them is required on create), which the spec leaves out.

  • Responses are read as the server sends them: a string property also accepts a JSON number (an available budget's spent_in_budgets[].currency_id is 1), a date-only field also accepts a date-time (a recurrence's first_date), and a budget without a currency of its own has a null CurrencyDecimalPlaces.

  • ConfigValueFilter, the title of each GET /v1/configuration entry, carries the editable configuration.* settings the spec lists only on ConfigValueUpdateFilter, and configuration.enable_batch_processing, which the spec lists nowhere. Without them the whole list failed to deserialize. An unrecognised title reads as Unknown, as with rule keywords; don't send it back. Checked against a live 6.7.9: all 33 settings read.

  • IDataApi.DestroyData's unused is a bool?: the spec types it as an int64 array, but the server validates it as true/false.

  • GET /v1/release-notes/{version} has two methods: GetReleaseNotes(version), and GetCurrentReleaseNotes() for the server's own version (the route makes {version} optional). The model's release_notes field is ReleaseNotesHtml, since a member cannot share the ReleaseNotes type'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's repeat_until and nr_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 = "" (or ObjectGroupId = 0); null is rejected.
    • A credit card's MonthlyPaymentDate stays while the account is a credit card; it is dropped when the update also changes AccountRole away from ccAsset.

    And some cannot be removed through the API at all: a bill's EndDate and ExtensionDate (null and "" are both rejected) and a piggy bank's group (an empty title is rejected, ObjectGroupId = 0 is accepted but changes nothing).

  • RuleTriggerUpdate.Prohibited (the "NOT" of a trigger) is sent on update too, although the spec lists it on RuleTriggerStore only.

  • CategoryUpdate.Notes and CategoryUpdate.Color are three-state, as the server treats them: never assigned (or null in the constructor) leaves the key out and the stored value unchanged; assigning null sends null and clears it; assigning a value sets it.

  • The other updates (AccountUpdate, BillUpdate, BudgetUpdate, BudgetLimitUpdate, PiggyBankUpdate, RecurrenceUpdate, TransactionSplitUpdate) leave notes out when Notes is null, which keeps the stored notes; assign "" to clear them. TransactionLinkUpdate is 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-dd via OpenAPIDateConverter; 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
Loading failed

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.