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

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

# 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

# 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

# List categories
curl "$BASE/categories"
# Create category
curl -X POST "$BASE/categories" -d '{"name": "Groceries"}'

Budgets

# 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)

# 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)

# 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

# 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)

# 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

# List tags
curl "$BASE/tags"
# Create tag
curl -X POST "$BASE/tags" -d '{"tag": "vacation"}'

Reports & Summary

# 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

curl "$BASE/categories" | jq '.data[] | {name: .attributes.name, spent: .attributes.spent}'

Get budget progress

curl "$BASE/budgets" | jq '.data[] | {name: .attributes.name, spent: .attributes.spent}'

Search transactions

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