Firefly III API Client

Access and manage Firefly III finance data programmatically, including transactions, accounts, recurring rules, and automation via the API.

Firefly III Client Skill

Purpose

A production-ready client for Firefly III personal finance management, allowing for programmatic access to transactions, accounts, recurring rules, and automation.

Security Considerations

See SECURITY.md for information on token safety, environment variables, and network security when using this skill.

Setup

1. Ensure Firefly III is running and you have an OAuth Personal Access Token.
2. Set the following environment variables:

   FIREFLY_URL=http://your-instance-url
   FIREFLY_TOKEN=your_personal_access_token
   

3. Install dependencies:

   pip install requests
   

CLI Reference

The api.py script serves as a generic wrapper for the Firefly III REST API.

• python3 api.py request <METHOD> <ENDPOINT> [-d <JSON_DATA>]

Examples

• List Accounts: python3 api.py request GET api/v1/accounts

• Create Transaction: python3 api.py request POST api/v1/transactions -d '{"amount": "10.00", "description": "Coffee", "source_id": 1, "destination_id": 2, "date": "2026-04-06", "type": "withdrawal"}'

• Create Recurring Transaction: python3 api.py request POST api/v1/recurrences -d '{"type": "withdrawal", "title": "Example", "first_date": "2026-04-30", "repeat_freq": "monthly", "nr_of_repetitions": 12, "repetitions": [{"type": "monthly", "moment": "30"}], "transactions": [{"description": "Item", "amount": "100.00", "source_id": 1, "destination_id": 2}]}'

• Create Rule: python3 api.py request POST api/v1/rules -d '{"title": "Example Rule", "trigger": "destination_account_is", "value": "Netflix", "action": "link_to_bill", "action_value": "Netflix Bill"}'