System

Cron job endpoint

GET

https://firefly.example.com/api/v1/cron/{cliToken}

Firefly III has one endpoint for its various cron related tasks. Send a GET to this endpoint to run the cron. The cron requires the CLI token to be present. The cron job will fire for all users.

Cron job endpoint

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

const response = await fetch('https://firefly.example.com/api/v1/cron/d5ea6b5fb774618dd6ad6ba6e0a7f55c', {
  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/cron/d5ea6b5fb774618dd6ad6ba6e0a7f55c',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "recurring_transactions": [
    {
      "job_fired": true,
      "job_succeeded": true,
      "job_errored": false,
      "message": "Cron result message",
      "user": "1"
    }
  ],
  "auto_budgets": [
    {
      "job_fired": true,
      "job_succeeded": true,
      "job_errored": false,
      "message": "Cron result message",
      "user": "1"
    }
  ],
  "exchange_rates": [
    {
      "job_fired": true,
      "job_succeeded": true,
      "job_errored": false,
      "message": "Cron result message",
      "user": "1"
    }
  ],
  "bill_notifications": [
    {
      "job_fired": true,
      "job_succeeded": true,
      "job_errored": false,
      "message": "Cron result message",
      "user": "1"
    }
  ],
  "webhooks": [
    {
      "job_fired": true,
      "job_succeeded": true,
      "job_errored": false,
      "message": "Cron result message",
      "user": "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"
}

Parameters

cliTokenstringrequiredpath

The CLI token of any user in Firefly III, required to run the cron job. OR this is the STATIC_CRON_TOKEN.

datestring<date>query

A date formatted YYYY-MM-DD. This can be used to make the cron job pretend it's running on another day.

forcebooleanquery

Forces the cron job to fire, regardless of whether it has fired before. This may result in double transactions or weird budgets, so be careful. Only system owners can do this.

Response

200OKCronResult

The result of the cron job(s) firing.

Response fields application/json

recurring_transactionsArray<CronResultRow>

Show child attributes

job_firedboolean | null

This value tells you if this specific cron job actually fired. It may not fire. Some cron jobs only fire every 24 hours, for example.

Example

true

job_succeededboolean | null

This value tells you if this specific cron job actually did something. The job may fire but not change anything.

Example

true

job_erroredboolean | null

If the cron job ran into some kind of an error, this value will be true.

Example

false

messagestring | null

If the cron job ran into some kind of an error, this value will be the error message. The success message if the job actually ran OK.

Example

Cron result message

userstring

The user for which this particular job result is.

Example

auto_budgetsArray<CronResultRow>

Show child attributes

job_firedboolean | null

This value tells you if this specific cron job actually fired. It may not fire. Some cron jobs only fire every 24 hours, for example.

Example

true

job_succeededboolean | null

This value tells you if this specific cron job actually did something. The job may fire but not change anything.

Example

true

job_erroredboolean | null

If the cron job ran into some kind of an error, this value will be true.

Example

false

messagestring | null

If the cron job ran into some kind of an error, this value will be the error message. The success message if the job actually ran OK.

Example

Cron result message

userstring

The user for which this particular job result is.

Example

exchange_ratesArray<CronResultRow>

Show child attributes

job_firedboolean | null

This value tells you if this specific cron job actually fired. It may not fire. Some cron jobs only fire every 24 hours, for example.

Example

true

job_succeededboolean | null

This value tells you if this specific cron job actually did something. The job may fire but not change anything.

Example

true

job_erroredboolean | null

If the cron job ran into some kind of an error, this value will be true.

Example

false

messagestring | null

If the cron job ran into some kind of an error, this value will be the error message. The success message if the job actually ran OK.

Example

Cron result message

userstring

The user for which this particular job result is.

Example

bill_notificationsArray<CronResultRow>

Show child attributes

job_firedboolean | null

This value tells you if this specific cron job actually fired. It may not fire. Some cron jobs only fire every 24 hours, for example.

Example

true

job_succeededboolean | null

This value tells you if this specific cron job actually did something. The job may fire but not change anything.

Example

true

job_erroredboolean | null

If the cron job ran into some kind of an error, this value will be true.

Example

false

messagestring | null

If the cron job ran into some kind of an error, this value will be the error message. The success message if the job actually ran OK.

Example

Cron result message

userstring

The user for which this particular job result is.

Example

webhooksArray<CronResultRow>

Show child attributes

job_firedboolean | null

This value tells you if this specific cron job actually fired. It may not fire. Some cron jobs only fire every 24 hours, for example.

Example

true

job_succeededboolean | null

This value tells you if this specific cron job actually did something. The job may fire but not change anything.

Example

true

job_erroredboolean | null

If the cron job ran into some kind of an error, this value will be true.

Example

false

messagestring | null

If the cron job ran into some kind of an error, this value will be the error message. The success message if the job actually ran OK.

Example

Cron result message

userstring

The user for which this particular job result is.

Example

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.