Rules

Store a new rule

POST

https://firefly.example.com/api/v1/rules

Creates a new rule. The data required can be submitted as a JSON body or as a list of parameters.

Store a new rule

curl -X POST 'https://firefly.example.com/api/v1/rules' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "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": [
    {
      "type": "user_action",
      "value": "tag1",
      "order": 5,
      "active": true,
      "prohibited": false,
      "stop_processing": false
    }
  ],
  "actions": [
    {
      "type": "set_category",
      "value": "Daily groceries",
      "order": 5,
      "active": true,
      "stop_processing": false
    }
  ]
}'

const body = `{
  "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": [
    {
      "type": "user_action",
      "value": "tag1",
      "order": 5,
      "active": true,
      "prohibited": false,
      "stop_processing": false
    }
  ],
  "actions": [
    {
      "type": "set_category",
      "value": "Daily groceries",
      "order": 5,
      "active": true,
      "stop_processing": false
    }
  ]
}`;

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

const data = await response.text();

import requests

body = '''{
  "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": [
    {
      "type": "user_action",
      "value": "tag1",
      "order": 5,
      "active": true,
      "prohibited": false,
      "stop_processing": false
    }
  ],
  "actions": [
    {
      "type": "set_category",
      "value": "Daily groceries",
      "order": 5,
      "active": true,
      "stop_processing": false
    }
  ]
}'''

response = requests.post(
    'https://firefly.example.com/api/v1/rules',
    data=body.encode('utf-8'),
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "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": [
    {
      "type": "user_action",
      "value": "tag1",
      "order": 5,
      "active": true,
      "prohibited": false,
      "stop_processing": false
    }
  ],
  "actions": [
    {
      "type": "set_category",
      "value": "Daily groceries",
      "order": 5,
      "active": true,
      "stop_processing": false
    }
  ]
}

{
  "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": [
    {
      "type": "user_action",
      "value": "tag1",
      "order": 5,
      "active": true,
      "prohibited": false,
      "stop_processing": false
    }
  ],
  "actions": [
    {
      "type": "set_category",
      "value": "Daily groceries",
      "order": 5,
      "active": true,
      "stop_processing": false
    }
  ]
}

{
  "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": "The given data was invalid.",
  "errors": {
    "email": [
      "string"
    ],
    "force": [
      "string"
    ],
    "blocked": [
      "string"
    ],
    "field": [
      "string"
    ],
    "role": [
      "string"
    ],
    "blocked_code": [
      "string"
    ],
    "name": [
      "string"
    ],
    "type": [
      "string"
    ],
    "iban": [
      "string"
    ],
    "start": [
      "string"
    ],
    "end": [
      "string"
    ],
    "date": [
      "string"
    ]
  }
}

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

Body

JSON array or key=value pairs with the necessary rule information. See the model for the exact specifications.

application/json,application/x-www-form-urlencodedRuleStore

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>

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

strictbooleantrue

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_processingboolean

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<RuleTriggerStore>required

Show child attributes

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

orderinteger<int32>

Order of the trigger

Example

activebooleantrue

If the trigger is active. Defaults to true.

Example

true

prohibitedbooleanfalse

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

Example

false

stop_processingbooleanfalse

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

Example

false

actionsArray<RuleActionStore>required

Show child attributes

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

Parameters

X-Trace-Idstring<uuid>header

Unique identifier associated with this request.

Response

200OKRuleSingle

New rule stored, result in response.

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

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

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

422Unprocessable EntityValidationErrorResponse

Validation error. The body will have the exact details.

Response fields application/json

messagestring

Example

The given data was invalid.

errorsobject

Show child attributes

emailArray<string>

forceArray<string>

blockedArray<string>

fieldArray<string>

roleArray<string>

blocked_codeArray<string>

nameArray<string>

typeArray<string>

ibanArray<string>

startArray<string>

endArray<string>

dateArray<string>

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.