Skip to main content
Firefly III provides a comprehensive RESTful API for programmatic access to all features of your personal finance manager.

​
Base URL

All API endpoints are prefixed with: 
/api/v1
Example full URL: 
https://your-firefly-instance.com/api/v1/accounts

​
API Versioning

Firefly III uses URL-based API versioning. The current version is v1, indicated by the /v1/ prefix in all endpoint URLs. The API version matches the Firefly III application version and is returned in the /api/v1/about endpoint.

​
Response Format

The API uses JSON API specification for structured responses.

​
Content Type

All responses use one of two content types:
  • application/vnd.api+json - JSON API format (default)
  • application/json - Standard JSON format

​
Accept Headers

Your requests must include an Accept header with one of:
  • application/json
  • application/vnd.api+json
curl -X GET "https://your-firefly-instance.com/api/v1/about" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Success Response

​
data
object
The main response data object containing the requested resource(s)
​
meta
object
Metadata about the response, including pagination information
​
links
object
HATEOAS links for navigation (pagination, related resources)
{
  "data": {
    "type": "accounts",
    "id": "1",
    "attributes": {
      "name": "Checking Account",
      "type": "asset",
      "currency_code": "USD"
    }
  },
  "meta": {
    "pagination": {
      "total": 100,
      "count": 50,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 2
    }
  },
  "links": {
    "self": "https://your-firefly-instance.com/api/v1/accounts?page=1",
    "first": "https://your-firefly-instance.com/api/v1/accounts?page=1",
    "next": "https://your-firefly-instance.com/api/v1/accounts?page=2",
    "last": "https://your-firefly-instance.com/api/v1/accounts?page=2"
  }
}

​
Error Handling

The API returns standard HTTP status codes and JSON error responses.

​
HTTP Status Codes

Status CodeDescription
200OK - Request succeeded
201Created - Resource created successfully
204No Content - Request succeeded with no response body
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing authentication
403Forbidden - Insufficient permissions
404Not Found - Resource not found
422Unprocessable Entity - Validation errors
500Internal Server Error - Server error

​
Error Response Format

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "type": [
      "The selected type is invalid."
    ]
  }
}
​
message
string
Human-readable error message
​
errors
object
Field-specific validation errors (when applicable)

​
Pagination

List endpoints support pagination using query parameters.
​
page
integer
default:"1"
Page number to retrieve (minimum: 1, maximum: 65536)
​
limit
integer
default:"50"
Number of items per page (minimum: 1, maximum: 65536)
curl -X GET "https://your-firefly-instance.com/api/v1/transactions?page=2&limit=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Pagination Response

Paginated responses include metadata:
​
meta.pagination.total
integer
Total number of items across all pages
​
meta.pagination.count
integer
Number of items in the current page
​
meta.pagination.per_page
integer
Items per page
​
meta.pagination.current_page
integer
Current page number
​
meta.pagination.total_pages
integer
Total number of pages

​
Date Parameters

Many endpoints accept date parameters for filtering.
​
start
date
Start date in YYYY-MM-DD format
​
end
date
End date in YYYY-MM-DD format
curl -X GET "https://your-firefly-instance.com/api/v1/transactions?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
System Information

Retrieve information about your Firefly III instance.

​
Get System Information

curl -X GET "https://your-firefly-instance.com/api/v1/about" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Current User

curl -X GET "https://your-firefly-instance.com/api/v1/about/user" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
The /api/v1/about endpoint returns version information and system details about your Firefly III installation.

​
Rate Limiting

Firefly III does not enforce API rate limits by default, but your hosting environment may impose limits.
Always implement proper error handling and retry logic in your API client to handle potential rate limiting or service interruptions.

​
CORS Support

Cross-Origin Resource Sharing (CORS) is supported. Configure CORS settings in your Firefly III installation if you’re accessing the API from a web browser.

​
Next Steps

Authentication

Learn how to authenticate API requests with OAuth2

Search API

Search transactions and accounts

Webhooks

Configure webhooks for real-time notifications

Data Operations

Bulk operations and data export