Skip to content

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.

RouteWhoWhat it returns
GET /api/diagnostics/reportSelf-hosted onlyThe installation report: summary, dependencies, configuration, modules, background work and recent errors.
GET /api/diagnostics/bundleSelf-hosted onlyThe 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/modulesEvery deploymentThe workspace's module matrix: why each module is on or off, with deployment.mode.
POST /api/diagnostics/checksEvery 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 ​

bash
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).

StatusMeaning
200The run finished.
400scope is not "workspace" or "installation".
401No session.
403The caller lacks the diagnostics permission (admin for POST /checks).
404installation scope, the report or the bundle on a hosted deployment.
429Checks 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.

Studio · Pulse · Console · Agent SDK and more — the Cognipeer documentation hub