firefly-iii

# Firefly III Firefly III is a self-hosted personal finance manager. This skill provides API access for managing finances. ## Configuration Required environment: - `FIREFLY_URL`: Base URL (e.g., `https://budget.example.com`) - `FIREFLY_TOKEN`: Personal Access Token (stored at `~/.firefly_token`) Get token: Profile → OAuth → Personal Access Tokens → Create new token ## API Basics ```bash TOKEN=$(cat ~/.firefly_token) BASE="$FIREFLY_URL/api/v1" curl -s "$BASE/endpoint" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" ``` ## Core Endpoints ### Accounts ```bash # List accounts curl "$BASE/accounts?type=asset" # asset|expense|revenue|liability # Create account curl -X POST "$BASE/accounts" -d '{ "name": "Bank Account", "type": "asset", "account_role": "defaultAsset", "currency_code": "EUR" }' ``` Account types: `asset`, `expense`, `revenue`, `liability` Asset roles: `defaultAsset`, `savingAsset`, `sharedAsset`, `ccAsset` ### Transactions ```bash # List transactions curl "$BASE/transactions?type=withdrawal&start=2026-01-01&end=2026-01-31" # Create withdrawal (expense) curl -X POST "$BASE/transactions" -d '{ "transactions": [{ "type": "withdrawal", "date": "2026-01-15", "amount": "50.00", "description": "Groceries", "source_name": "Bank Account", "destination_name": "Supermarket", "category_name": "Groceries" }] }' # Create deposit (income) curl -X POST "$BASE/transactions" -d '{ "transactions": [{ "type": "deposit", "date": "2026-01-01", "amount": "3000.00", "description": "Salary", "source_name": "Employer", "destination_name": "Bank Account", "category_name": "Salary" }] }' # Create transfer curl -X POST "$BASE/transactions" -d '{ "transactions": [{ "type": "transfer", "date": "2026-01-05", "amount": "500.00", "description": "Savings", "source_name": "Bank Account", "destination_name": "Savings Account" }] }' ``` Transaction types: `withdrawal`, `deposit`, `transfer` ### Categories ```bash # List categories curl "$BASE/categories" # Create category curl -X POST "$BASE/categories" -d '{"name": "Groceries"}' ``` ### Budgets ```bash # List budgets curl "$BASE/budgets" # Create budget curl -X POST "$BASE/budgets" -d '{"name": "Food", "active": true}' # Set budget limit for period curl -X POST "$BASE/budgets/{id}/limits" -d '{ "start": "2026-01-01", "end": "2026-01-31", "amount": "500.00" }' ``` ### Piggy Banks (Savings Goals) ```bash # List piggy banks curl "$BASE/piggy-banks" # Create piggy bank curl -X POST "$BASE/piggy-banks" -d '{ "name": "Vacation Fund", "target_amount": "2000.00", "accounts": [{"account_id": "1"}], "start_date": "2026-01-01", "target_date": "2026-12-31", "transaction_currency_code": "EUR" }' # Add money to piggy bank curl -X POST "$BASE/piggy-banks/{id}/events" -d '{"amount": "100.00"}' ``` ### Subscriptions (Bills) ```bash # List subscriptions curl "$BASE/subscriptions" # Create subscription curl -X POST "$BASE/subscriptions" -d '{ "name": "Netflix", "amount_min": "12.99", "amount_max": "12.99", "date": "2026-01-15", "repeat_freq": "monthly", "currency_code": "EUR" }' ``` Repeat frequencies: `weekly`, `monthly`, `quarterly`, `half-year`, `yearly` ### Recurring Transactions ```bash # List recurring transactions curl "$BASE/recurrences" # Create recurring transaction curl -X POST "$BASE/recurrences" -d '{ "type": "withdrawal", "title": "Rent", "first_date": "2026-01-01", "repeat_until": "2026-12-31", "repetitions": [{ "type": "monthly", "moment": "1" }], "transactions": [{ "amount": "1000.00", "description": "Monthly rent", "source_id": "1", "destination_name": "Landlord", "category_name": "Rent" }] }' ``` ### Rules (Auto-categorization) ```bash # List rules curl "$BASE/rules" # Create rule curl -X POST "$BASE/rules" -d '{ "title": "Categorize groceries", "trigger": "store-journal", "active": true, "strict": false, "triggers": [ {"type": "description_contains", "value": "ALDI"} ], "actions": [ {"type": "set_category", "value": "Groceries"} ] }' ``` Trigger types: `description_contains`, `description_starts`, `description_ends`, `amount_less`, `amount_more`, `source_account_is`, etc. Action types: `set_category`, `set_budget`, `add_tag`, `set_description`, etc. ### Tags ```bash # List tags curl "$BASE/tags" # Create tag curl -X POST "$BASE/tags" -d '{"tag": "vacation"}' ``` ### Reports & Summary ```bash # Account balance over time curl "$BASE/accounts/{id}/transactions?start=2026-01-01&end=2026-01-31" # Get current balances curl "$BASE/accounts" | jq '.data[] | {name: .attributes.name, balance: .attributes.current_balance}' ``` ## Common Tasks ### Get spending by category ```bash curl "$BASE/categories" | jq '.data[] | {name: .attributes.name, spent: .attributes.spent}' ``` ### Get budget progress ```bash curl "$BASE/budgets" | jq '.data[] | {name: .attributes.name, spent: .attributes.spent}' ``` ### Search transactions ```bash curl "$BASE/search/transactions?query=groceries&limit=25" ``` ## Error Handling - `422 Unprocessable Entity`: Check required fields in error response - `401 Unauthorized`: Token expired or invalid - `404 Not Found`: Resource doesn't exist ## Tips - Use `source_name`/`destination_name` to auto-create expense/revenue accounts - Categories are different from budgets (categories for classification, budgets for limits) - Piggy banks require linking to an asset account - Use rules to auto-categorize transactions on creation