Diagnostics API
The routes behind Settings → Diagnostics: a report of how the installation is set up, why each module of the workspace is on or off, and live checks of the integrations. They are dashboard routes under /api/diagnostics: they authenticate with a browser session (not an API token) and read the signed-in workspace. The screen and the command-line doctor are described in Monitoring.
Access
The routes belong to the diagnostics permission service. Owners and administrators hold it by default, and a read grant opens the reads to other people. Running live checks needs admin. Every response is Cache-Control: no-store.
On a hosted deployment the installation belongs to the operator, not to a workspace: the report, the bundle and the installation checks answer 404 there, and a workspace sees its own module matrix and checks its own integrations only. Self-hosted deployments have every route.
| Route | Who | What it returns |
|---|---|---|
GET /api/diagnostics/report | Self-hosted only | The installation report: summary, dependencies, configuration, modules, background work and recent errors. |
GET /api/diagnostics/bundle | Self-hosted only | The same report as a JSON file to send to support (Content-Disposition: attachment). Secrets are masked; it holds no conversations, documents or personal data. Taking it is written to the audit log (diagnostics.bundle.download). |
GET /api/diagnostics/modules | Every deployment | The workspace's module matrix: why each module is on or off, with deployment.mode. |
POST /api/diagnostics/checks | Every deployment (admin) | Test now: live checks. Body { "scope": "workspace" } checks the workspace's own integrations; { "scope": "installation" } checks the installation (self-hosted only). |
The reads call nothing outside the installation; only an explicit live-check run does.
Live checks
curl -X POST "$CONSOLE_URL/api/diagnostics/checks" \
-H "Content-Type: application/json" \
-H "Cookie: $SESSION_COOKIE" \
-d '{ "scope": "workspace" }'The answer is a run summary with the individual check results, the counts per outcome and the duration. Running checks is audited (diagnostics.checks.run, counts only; the messages stay on the page).
| Status | Meaning |
|---|---|
200 | The run finished. |
400 | scope is not "workspace" or "installation". |
401 | No session. |
403 | The caller lacks the diagnostics permission (admin for POST /checks). |
404 | installation scope, the report or the bundle on a hosted deployment. |
429 | Checks ran a moment ago; the body has retryAfterSeconds and the response has Retry-After. |
Command line
When the console does not open, npm run doctor builds the same report from a shell: --json prints the full report, --bundle [path] writes the support bundle file, --tenant <slug> adds the module matrix and recent errors of one workspace. Inside the image run node scripts/doctor.mjs.

