Attachments

Get a single attachment.

GET

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

Get a single attachment. This endpoint only returns the available metadata for the attachment. Actual file data is handled in two other endpoints (see below).

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

{
  "data": {
    "type": "attachments",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "attachable_type": "Bill",
      "attachable_id": "134",
      "hash": "0c3f95f34370baa88f9fd9a671fea305",
      "filename": "file.pdf",
      "download_url": "https://demo.firefly-iii.org/api/v1/attachments/191/download",
      "upload_url": "https://demo.firefly-iii.org/api/v1/attachments/191/download",
      "title": "Some PDF file",
      "notes": "Some notes",
      "mime": "application/pdf",
      "size": 48211
    },
    "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 attachment.

Response

200OKAttachmentSingle

The requested attachment

Response fields application/vnd.api+json

dataAttachmentReadrequired

Show child attributes

typestringrequired

Immutable value

Example

attachments

idstringrequired

Example

attributesAttachmentPropertiesrequired

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

attachable_typeAttachableTypeAccountBudgetBillTransactionJournalPiggyBankTag

The object class to which the attachment must be linked.

Example

Bill

attachable_idstring

ID of the model this attachment is linked to.

Example

hashstring

Hash of the file for basic duplicate detection.

Example

0c3f95f34370baa88f9fd9a671fea305

filenamestring

Example

file.pdf

download_urlstring

Example

https://demo.firefly-iii.org/api/v1/attachments/191/download

upload_urlstring

Example

https://demo.firefly-iii.org/api/v1/attachments/191/download

titlestring | null

Example

Some PDF file

notesstring | null

Example

Some notes

mimestringread only

Example

application/pdf

sizeinteger<int32>read only

Example

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.