Get a single category.

GET

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

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

{
  "data": {
    "type": "categories",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "name": "Lunch",
      "color": "FF0000",
      "last_activity": "2026-10-01T00:00:00+00:00",
      "notes": "Some example notes",
      "object_has_currency_setting": false,
      "primary_currency_id": "5",
      "primary_currency_name": "Euro",
      "primary_currency_code": "EUR",
      "primary_currency_symbol": "$",
      "primary_currency_decimal_places": 2,
      "spent": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ],
      "pc_spent": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ],
      "earned": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ],
      "pc_earned": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ],
      "transferred": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ],
      "pc_transferred": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ]
    }
  }
}

{
  "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 category.

startstring<date>query

A date formatted YYYY-MM-DD, to show spent and earned info.

endstring<date>query

A date formatted YYYY-MM-DD, to show spent and earned info.

Response

200OKCategorySingle

The requested category

Response fields application/vnd.api+json

dataCategoryReadrequired

Show child attributes

typestringrequired

Immutable value

Example

categories

idstringrequired

Example

attributesCategoryPropertiesrequired

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

namestringrequired

Example

Lunch

colorstring

The color of the category in HEX format. Firefly III does not use this field, but your app might.

Example

FF0000

last_activitystring<date-time> | null

Last activity of the category.

Example

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

notesstring | null

Example

Some example notes

object_has_currency_settingboolean

This object never has its own currency setting, so this value is always false.

Example

false

primary_currency_idstringread only

The currency ID of the administration's primary currency.

Example

primary_currency_namestringread only

The currency name of the administration's primary currency.

Example

Euro

primary_currency_codestringread only

The currency code of the administration's primary currency.

Example

EUR

primary_currency_symbolstringread only

The currency symbol of the administration's primary currency.

Example

primary_currency_decimal_placesinteger<int32>read only

The currency decimal places of the administration's primary currency.

Example

spentArray<ArrayEntryWithCurrencyAndSum>read only

Amount(s) spent in the currencies in the database for this category. ONLY present when start and date are set.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

pc_spentArray<ArrayEntryWithCurrencyAndSum>read only

Amount(s) spent in the primary currency in the database for this category. ONLY present when start and date are set.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

earnedArray<ArrayEntryWithCurrencyAndSum>read only

Amount(s) earned in the currencies in the database for this category. ONLY present when start and date are set.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

pc_earnedArray<ArrayEntryWithCurrencyAndSum>read only

Amount(s) earned in the primary currency in the database for this category. ONLY present when start and date are set.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

transferredArray<ArrayEntryWithCurrencyAndSum>read only

Amount(s) transferred in the currencies in the database for this category. ONLY present when start and date are set.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

pc_transferredArray<ArrayEntryWithCurrencyAndSum>read only

Amount(s) transferred in primary currency in the database for this category. ONLY present when start and date are set.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

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.