Skip to main content

​
Overview

The Budgets API allows you to create and manage budgets, set budget limits, and track spending against budgeted amounts. Budgets help you control expenses by allocating specific amounts for different categories.

​
List All Budgets

curl -X GET "https://demo.firefly-iii.org/api/v1/budgets" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/budgets

​
Query Parameters

​
page
integer
Page number for pagination
​
start
string
Start date for spent amounts (YYYY-MM-DD)
​
end
string
End date for spent amounts (YYYY-MM-DD)

​
Response Fields

​
id
string
Budget ID
​
created_at
string
ISO 8601 timestamp of creation
​
updated_at
string
ISO 8601 timestamp of last update
​
active
boolean
Whether the budget is active
​
name
string
Budget name
​
order
integer
Display order
​
notes
string
Budget notes
​
auto_budget_type
string
Auto-budget type: reset, rollover, adjusted, or null
​
auto_budget_period
string
Auto-budget period: daily, weekly, monthly, quarterly, half_year, yearly
​
auto_budget_amount
string
Amount for auto-budget
​
pc_auto_budget_amount
string
Auto-budget amount in primary currency
​
object_has_currency_setting
boolean
Whether budget has specific currency settings
​
currency_id
string
Auto-budget currency ID
​
currency_code
string
Currency code
​
currency_name
string
Currency name
​
currency_symbol
string
Currency symbol
​
currency_decimal_places
integer
Decimal places for currency
​
spent
array
Array of spent amounts per currency
​
pc_spent
array
Array of spent amounts in primary currency

​
Create Budget

curl -X POST "https://demo.firefly-iii.org/api/v1/budgets" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Groceries",
    "active": true,
    "auto_budget_type": "reset",
    "auto_budget_amount": "500.00",
    "auto_budget_period": "monthly",
    "auto_budget_currency_code": "USD",
    "notes": "Monthly grocery budget"
  }'
Endpoint: POST /v1/budgets

​
Request Body

​
name
string
required
Budget name (1-255 characters, must be unique)
​
active
boolean
default:"true"
Whether the budget is active
​
order
integer
Display order for the budget
​
notes
string
Budget notes (max 32,768 characters)
​
auto_budget_type
string
Auto-budget type: reset, rollover, adjusted, or none
​
auto_budget_amount
string
Amount for auto-budget (required if auto_budget_type is reset, rollover, or adjusted)
​
auto_budget_period
string
Period: daily, weekly, monthly, quarterly, half_year, yearly (required if auto-budget type is set)
​
auto_budget_currency_id
integer
Currency ID for auto-budget (must exist in transaction_currencies)
​
auto_budget_currency_code
string
Currency code for auto-budget (must exist in transaction_currencies)
​
fire_webhooks
boolean
default:"true"
Trigger webhooks for this budget
Auto-Budget Types:
  • reset: Budget resets to the specified amount each period
  • rollover: Unused budget rolls over to the next period
  • adjusted: Budget adjusts based on actual spending
  • none: No automatic budget management

​
Get Budget by ID

curl -X GET "https://demo.firefly-iii.org/api/v1/budgets/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/budgets/{id} Returns the same response fields as the List endpoint.

​
Update Budget

curl -X PUT "https://demo.firefly-iii.org/api/v1/budgets/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Groceries Budget",
    "auto_budget_amount": "600.00",
    "notes": "Increased for inflation"
  }'
Endpoint: PUT /v1/budgets/{id} Accepts the same parameters as Create Budget. All fields are optional.

​
Delete Budget

curl -X DELETE "https://demo.firefly-iii.org/api/v1/budgets/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: DELETE /v1/budgets/{id} Deletes the budget and all associated budget limits.
Deleting a budget does not delete transactions, but it removes the budget association from those transactions.

​
Budget Limits

​
List Budget Limits

Endpoint: GET /v1/budgets/{budget}/limits Returns all budget limits for a specific budget.

​
Create Budget Limit

curl -X POST "https://demo.firefly-iii.org/api/v1/budgets/{budget}/limits" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2024-01-01",
    "end": "2024-01-31",
    "amount": "500.00",
    "currency_code": "USD"
  }'
Endpoint: POST /v1/budgets/{budget}/limits Creates a budget limit for a specific time period.

​
Get Budget Limit

Endpoint: GET /v1/budgets/{budget}/limits/{budgetLimit} Returns details of a specific budget limit.

​
Update Budget Limit

Endpoint: PUT /v1/budgets/{budget}/limits/{budgetLimit} Updates an existing budget limit.

​
Delete Budget Limit

Endpoint: DELETE /v1/budgets/{budget}/limits/{budgetLimit} Deletes a budget limit.

​
Get Budget Limit Transactions

Endpoint: GET /v1/budgets/{budget}/limits/{budgetLimit}/transactions Returns all transactions within a budget limit period.

​
Get Budget Transactions

Endpoint: GET /v1/budgets/{id}/transactions Returns all transactions associated with this budget.

​
Get Budget Attachments

Endpoint: GET /v1/budgets/{id}/attachments Returns all attachments for this budget.

​
Get Transactions Without Budget

Endpoint: GET /v1/budgets/transactions-without-budget Returns all transactions that don’t have a budget assigned.

​
List All Budget Limits

Endpoint: GET /v1/budget-limits Returns all budget limits across all budgets.