Monitoring Paperless-ngx in Home-Assistant

Paperless-ngx is my document management system of choice, and of course I want statistics from this in Home-Assistant.

There is no integration, but there is an API that can be used, and that is what i used to extract data about total documents, documents owned per user, and amount of documents in the inbox. These are the metrics I find useful to Monitor in Home-Assistant.

My Paperless-ngx card in Home-Assistant now look like this:

In this post I will describe how I did it, so you can to!

Creating a user for API calls

You don’t need a dedicated user for the API calls, just a superuser. But I find a dedicated user the be the best practise for these things.

Create User

Log in to the Paperless-ngx UI with a superuser
Go to Settings and click Open Django Admin.
Click +Add next to Users
Create a user with a password, my user is named “homeassistant”
Click Save and continue editing
Check Superuser status and click SAVE

Generate token

Click +Add next to Tokens
Select User: homeassistant and SAVE
Copy the KEY “40da7b4a405a9dedf0d965bdcb5c1fcde0484065“

Finding ID’s for Paperless-ngx objects

For the metrics needed I need the ID for the inbox tag and for the users, me and my wife. I will describe how I get it here. However this step is the same for all object categories like document_types, storage_paths ect if that is something you want to monitor.

In the examples below I use curl with jq. You can do the exact same calls just by sing the Django REST framework GUI included in Paperless-ngx. just navigate to http://<paperless-ngx_ip>:<port>/api/

Finding the id for a tag

You can find the ID for a tag (like the INBOX tag) with CURL.

curl -H "Authorization: Token 47a2345b7cd4e8f43a0bc33defabcde7fabcdef5" http://<paperless-ngx_ip>:<port>/api/tags/ | jq

Below you can see my tag with the name inbox has the id of 1, you also see that it has is_inbox_tag set to true, indicating it is also working as a inbox. It also has document_count value of 1, indicating that is is one item in the inbox right now.

    {
      "id": 1,
      "slug": "inbox",
      "name": "inbox",
      "colour": 1,
      "match": "",
      "matching_algorithm": 6,
      "is_insensitive": true,
      "is_inbox_tag": true,
      "document_count": 1,
      "owner": null,
      "user_can_change": true
    },

Finding the id for a user

You can find the ID for a user with CURL.

curl -H "Authorization: Token 47a2345b7cd4e8f43a0bc33defabcde7fabcdef5" http://<paperless-ngx_ip>:<port>/api/users/ | jq

Below you can see my user “fleska”, it has the id of 3.

{
      "id": 3,
      "username": "fleska",
      "email": "",
      "password": "**********",
      "first_name": "Flemming",
      "last_name": "******",
      "date_joined": "2023-03-11T20:23:58+01:00",
      "is_staff": true,
      "is_active": true,
      "is_superuser": true,
      "groups": [
        1
      ],
      "user_permissions": [],
      "inherited_permissions": [
        "#A lot of permissions"
      ]
    },

Home-Assistant Sensors

The sensors can be copy-pasted in to your Home-Assistant configuration.yaml file, all of them are using the RESTful sensor.

Sensor for total number of Documents in Paperless-ngx

sensor:
  - platform: rest
    name: Paperless-ngx - Number of documents in Total
    resource: http://<paperless-ngx_ip>:<port>/api/documents/
    method: GET
    headers:
      Authorization: Token 47a2345b7cd4e8f43a0bc33defabcde7fabcdef5
    value_template: "{{ value_json.count }}"
    scan_interval: 300

Sensor for number of documents in the inbox (tag with ID “1” seen in the resource url /1/)

sensor:
  - platform: rest
    name: Paperless-ngx - Total documents in tag inbox
    resource: http://<paperless-ngx_ip>:<port>/api/tags/1/
    method: GET
    headers:
      Authorization: Token 47a2345b7cd4e8f43a0bc33defabcde7fabcdef5
    value_template: "{{ value_json.document_count }}"
    scan_interval: 300

Sensor for number of documents owned by fleska (user with ID “3”. see ?owner__id=3)

sensor:
  - platform: rest
    name: Paperless-ngx - Number of documents owned by user id3
    resource: http://<paperless-ngx_ip>:<port>/api/documents/?owner__id=3
    method: GET
    headers:
      Authorization: Token 47a2345b7cd4e8f43a0bc33defabcde7fabcdef5
    value_template: "{{ value_json.count }}"
    scan_interval: 300

Dashboard

I am using the custom:mushroom-template-card available in HACS for this, but you can just use the normal entities card for a simple solution, however this is my card config:

type: custom:mushroom-template-card
primary: Paperless-ngx
secondary: >-
  {{ states("sensor.paperless_ngx_total_documents_in_tag_inbox") }} documents in
  inbox

  {{ states("sensor.paperless_ngx_number_of_documents_in_total") }} total
  documents

  {{ states("sensor.paperless_ngx_number_of_documents_owned_by_user_id4") }} owned
  by User with ID 4 / {{
  states("sensor.paperless_ngx_number_of_documents_owned_by_user_id3") }} owned by
  User  with ID 3
picture: /local/custom_graphics/paperless-ngx_logo.png
multiline_secondary: true
tap_action:
  action: url
  url_path: https://paperless-ngx.mydomain.com/
hold_action:
  action: none
double_tap_action:
  action: none
icon: ''

PS: The logo in my card is downloaded from Google Play and converted to PNG.

Sources