Rules

Get a single rule.

GET

https://firefly.example.com/api/v1/rules/{id}

Get a single rule.

curl -X GET 'https://firefly.example.com/api/v1/rules/123' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://firefly.example.com/api/v1/rules/123', {
  method: 'GET',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://firefly.example.com/api/v1/rules/123',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "data": {
    "type": "rules",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "title": "First rule title.",
      "description": "First rule description",
      "rule_group_id": "81",
      "rule_group_title": "New rule group",
      "order": 5,
      "trigger": "store-journal",
      "active": true,
      "strict": true,
      "stop_processing": false,
      "triggers": [
        {
          "id": "2",
          "created_at": "2026-10-01T00:00:00+00:00",
          "updated_at": "2026-10-01T00:00:00+00:00",
          "type": "user_action",
          "value": "tag1",
          "prohibited": false,
          "order": 5,
          "active": true,
          "stop_processing": false
        }
      ],
      "actions": [
        {
          "id": "2",
          "created_at": "2026-10-01T00:00:00+00:00",
          "updated_at": "2026-10-01T00:00:00+00:00",
          "type": "set_category",
          "value": "Daily groceries",
          "order": 5,
          "active": true,
          "stop_processing": false
        }
      ]
    },
    "links": {
      "0": {
        "rel": "self",
        "uri": "/OBJECTS/1"
      },
      "self": "https://demo.firefly-iii.org/api/v1/OBJECTS/1"
    }
  }
}

{
  "message": "Bad Request",
  "exception": "BadRequestHttpException"
}

{
  "message": "Unauthenticated",
  "exception": "AuthenticationException"
}

{
  "message": "Resource not found",
  "exception": "NotFoundHttpException"
}

{
  "message": "Internal Exception",
  "exception": "InternalException"
}

Parameters

idstringrequiredpath

The ID of the object.

Response

200OKRuleSingle

The requested rule

Response fields application/vnd.api+json

dataRuleReadrequired

Show child attributes

typestringrequired

Immutable value

Example

rules

idstringrequired

Example

attributesRulerequired

Show child attributes

created_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

updated_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

titlestringrequired

Example

First rule title.

descriptionstring

Example

First rule description

rule_group_idstringrequired

ID of the rule group under which the rule must be stored. Either this field or rule_group_title is mandatory.

Example

rule_group_titlestring

Title of the rule group under which the rule must be stored. Either this field or rule_group_id is mandatory.

Example

New rule group

orderinteger<int32>read only

Example

triggerRuleTriggerTypestore-journalupdate-journalmanual-activationrequired

Which action is necessary for the rule to fire? Use either store-journal, update-journal or manual-activation.

Example

store-journal

activebooleantrue

Whether or not the rule is even active. Default is true.

Example

true

strictboolean

If the rule is set to be strict, ALL triggers must hit in order for the rule to fire. Otherwise, just one is enough. Default value is true.

Example

true

stop_processingbooleanfalse

If this value is true and the rule is triggered, other rules after this one in the group will be skipped. Default value is false.

Example

false

triggersArray<RuleTrigger>required

Show child attributes

idstringread only

Example

created_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

updated_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

typeRuleTriggerKeywordfrom_account_startsfrom_account_endsfrom_account_isfrom_account_containsto_account_startsto_account_endsto_account_isto_account_containsamount_lessamount_exactlyamount_moredescription_startsdescription_endsdescription_containsdescription_istransaction_typecategory_isbudget_istag_iscurrency_ishas_attachmentshas_no_categoryhas_any_categoryhas_no_budgethas_any_budgethas_no_taghas_any_tagnotes_containsnotes_startsnotes_endnotes_areno_notesany_notessource_account_isdestination_account_issource_account_startsrequired

The type of thing this trigger responds to. A limited set is possible

Example

user_action

valuestringrequired

The accompanying value the trigger responds to. This value is often mandatory, but this depends on the trigger.

Example

tag1

prohibitedbooleanfalse

If 'prohibited' is true, this rule trigger will be negated. 'Description is' will become 'Description is NOT' etc.

Example

false

orderinteger<int32>read only

Order of the trigger

Example

activebooleantrue

If the trigger is active. Defaults to true.

Example

true

stop_processingbooleanfalse

When true, other triggers will not be checked if this trigger was triggered. Defaults to false.

Example

false

actionsArray<RuleAction>required

Show child attributes

idstringread only

Example

created_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

updated_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

typeRuleActionKeyworduser_actionset_categoryclear_categoryset_budgetclear_budgetadd_tagremove_tagremove_all_tagsset_descriptionappend_descriptionprepend_descriptionset_source_accountset_destination_accountset_notesappend_notesprepend_notesclear_noteslink_to_billconvert_withdrawalconvert_depositconvert_transferdelete_transactionrequired

The type of thing this action will do. A limited set is possible.

Example

set_category

valuestring | nullrequired

The accompanying value the action will set, change or update. Can be empty, but for some types this value is mandatory.

Example

Daily groceries

orderinteger<int32>

Order of the action

Example

activebooleantrue

If the action is active. Defaults to true.

Example

true

stop_processingbooleanfalse

When true, other actions will not be fired after this action has fired. Defaults to false.

Example

false

linksObjectLinkrequired

Show child attributes

0object

Show child attributes

relstring

Example

self

uristring

Example

/OBJECTS/1

selfstring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECTS/1

400Bad RequestBadRequestResponse

Bad request

Response fields application/json

messagestring

Example

Bad Request

exceptionstring

Example

BadRequestHttpException

401UnauthorizedUnauthenticatedResponse

Unauthenticated

Response fields application/json

messagestring

Example

Unauthenticated

exceptionstring

Example

AuthenticationException

404Not FoundNotFoundResponse

Page not found

Response fields application/json

messagestring

Example

Resource not found

exceptionstring

Example

NotFoundHttpException

500Internal Server ErrorInternalExceptionResponse

Internal exception

Response fields application/json

messagestring

Example

Internal Exception

exceptionstring

Example

InternalException

Authorization

firefly_iii_authoauth2

OAuth2 authorization code flow. Create a client on your installation's /profile page; it authorizes at /oauth/authorize and issues tokens at /oauth/token there. The URLs below are the demo site's. How to use the API walks through it.

local_bearer_authhttp (bearer)

A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.