[Feature Request] Add /health endpoint for system monitoring

[Ezehkiel]

Description

Summary
It would be very useful to expose a /health endpoint in Paperless-ngx that returns the same information currently available in the System Status page of the web interface.
This would allow administrators to easily integrate Paperless into monitoring systems such as Zabbix, Prometheus, or similar tools.

Motivation

• Currently, system status can only be checked manually through the web interface.
• For automated monitoring, a JSON endpoint would provide a machine-readable format.
• This would help detect issues (e.g., database down, version mismatch, storage running low, failed sanity checks) before they affect users.

Proposed Solution
Expose a /health endpoint (e.g., /api/health/) that returns the following information in JSON:

{
  "environment": {
    "paperless_ngx_version": {
      "backend": "2.18.3",
      "frontend": "2.18.2",
      "status": "mismatch"
    },
    "install_type": "docker",
    "server_os": "Linux-6.1.0-38-amd64-x86_64-with-glibc2.36",
    "media_storage": {
      "available_gb": 11.5,
      "total_gb": 48.0,
      "usage_percent": 76.0
    }
  },
  "database": {
    "type": "postgresql",
    "status": "ok",
    "migration_status": "up_to_date"
  },
  "tasks_queue": {
    "redis_status": "ok",
    "celery_status": "ok"
  },
  "health": {
    "search_index": {
      "status": "ok",
      "runnable": true
    },
    "classifier": {
      "status": "ok",
      "runnable": true
    },
    "sanity_checker": {
      "status": "warning",
      "runnable": true
    }
  }
}

Benefits

• Enables monitoring integrations without scraping the web UI.
• Provides early warnings for problems (low disk space, failed tasks, inconsistent versions).
• Standardizes system health reporting for Paperless-ngx deployments.

Other

No response

[shamoon]

System status has an api endpoint, all of the UI works through the api

[Ezehkiel]

Thanks for the quick reply!

That works fine when authentication is available without SSO but in my setup I have SSO enabled and I force login for all endpoints. This means that when my monitoring system (e.g. Zabbix) tries to access the system status API, it gets redirected to the SSO login page instead of receiving a JSON payload.

For monitoring purposes, it would be very helpful if the health/status endpoint could:

• be accessible without authentication, or
• have a configuration option to bypass SSO enforcement for this specific path.

Without this, external monitoring tools can’t fetch the status, even though the API exists.

[shamoon]

To clarify regarding the post above, we are not going to expose privileged information like this without auth, that would be wildly insecure. This request is more plausible, though different: #10773 (comment)

[alteriks]

@Ezehkiel
I don't know which SSO you are using, but as far as I'm concerned, most popular OIDC solutions support bypassing authentication for:

• specific domains
• specific endpoints
• hosts / networks

Here is a working solution for Authelia:

# yaml-language-server: $schema=https://www.authelia.com/schemas/v4.38/json-schema/configuration.json

###############################################################
#                   Authelia ACL                              #
###############################################################

access_control:
  default_policy: 'deny'
  rules:
    - domain:
        - paperless.xxx.yyy
      resources:
        - '^/api([/?].*)?$'
      networks:
        - '10.1.1.0/24'
      policy: bypass

Most monitoring solutions support adding custom headers used for probing.
Once you create a user with read-only permissions to query the Paperless-NGX API, you can use the following header:

Authorization: Token _____YOUR____RO____TOKEN

Example request:

curl -X 'GET' -v --http1.1 -s \
  -H 'Authorization: Token _____YOUR____RO____TOKEN' \
  'https://paperless.xxx.yyy/api/status/'

---

@shamoon
My main gripe with the current solution—/api/status—is that it's quite expensive.
I'm running Paperless on a VM with 4× Ryzen 5650G, and querying it from the local LAN takes more than 1 second.

I’d like to have simple /api/health endpoint that only returns:

{
  "status": "OK"
}

…without querying the entire Paperless stack. It would be great if this endpoint was cheap to query - response time should be less than 20ms.

[shamoon]

Though related, that is a pretty different request than the original post so if you’d like to see that I’d suggest a separate feature request and I’d be happy to implement it if there is interest

[github-actions[bot]]

This discussion has been automatically closed because it was marked as answered. Please see our contributing guidelines for more details.

[github-actions[bot]]

This discussion has been automatically locked since there has not been any recent activity after it was closed. Please open a new discussion for related concerns. See our contributing guidelines for more details.