> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vigolium API Reference, Diagnostics

> System readiness check covering database connectivity, agent provider, third-party tools, and directory configuration.

## GET /api/diagnostics, System Readiness Check

Returns a diagnostic report checking database connectivity, agent provider readiness, third-party tools, and directory configuration. Useful for verifying the scanner is ready to operate before starting scans.

**Auth:** Viewer (requires Bearer token)

```bash theme={null}
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:9002/api/diagnostics | jq .
```

```json theme={null}
{
  "status": "degraded",
  "timestamp": "2026-04-29T03:40:08+08:00",
  "database": {
    "status": "ok",
    "message": "driver=sqlite"
  },
  "queue": {
    "status": "ok",
    "message": "depth=0"
  },
  "agent": {
    "status": "ok",
    "name": "olium",
    "provider": "openai-codex-oauth",
    "model": "gpt-5.5"
  },
  "browser": {
    "status": "warning",
    "message": "disabled in config"
  },
  "tools": {
    "chromium": {
      "status": "ok",
      "path": "/opt/homebrew/bin/chromium"
    }
  },
  "templates_dir": {
    "status": "ok",
    "message": "path=~/.vigolium/prompts, templates=38"
  },
  "sessions_dir": {
    "status": "ok",
    "message": "path=~/.vigolium/agent-sessions, writable=true"
  }
}
```

### Top-Level Status

| Value       | Meaning                                                                         |
| ----------- | ------------------------------------------------------------------------------- |
| `ready`     | All checks passed                                                               |
| `degraded`  | Some non-critical checks failed (e.g., optional tool missing, browser disabled) |
| `not_ready` | Critical checks failed (database or agent unavailable)                          |

### Check Statuses

Each individual check returns one of: `ok`, `warning`, `error`.

### Checks Performed

| Check            | Critical | Description                                                                                                                                                                                     |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `database`       | Yes      | Pings the database with a 2s timeout                                                                                                                                                            |
| `agent`          | Yes      | Resolves the configured olium provider and confirms credentials are available                                                                                                                   |
| `queue`          | No       | Reports queue depth and error counts                                                                                                                                                            |
| `browser`        | No       | Checks `agent-browser` binary if enabled in config                                                                                                                                              |
| `tools.chromium` | No       | Resolves the chromium/chrome binary (fallbacks: `chromium-browser`, `google-chrome`, `google-chrome-stable`). On the one-shot CLI paths it also smoke-launches the browser — see the note below |
| `tools.piolium`  | No       | Reports whether the optional piolium harness is installed under `~/.piolium`                                                                                                                    |
| `templates_dir`  | No       | Verifies prompt templates directory exists and contains `.md` files                                                                                                                             |
| `sessions_dir`   | No       | Verifies agent sessions directory exists and is writable                                                                                                                                        |

<Note>
  **Browser smoke-test on the CLI paths.** On the one-shot CLI paths — `vigolium doctor` and the first-run dependency check — the `tools.chromium` check goes beyond reading the `--version` banner: it *actually launches* the resolved Chromium headless, performing the same DevTools remote-debugging handshake the spider relies on, in an isolated self-cleaning user-data dir, bounded to \~30s. A binary that prints a version but SIGTRAPs / crashes on real launch (seen with some distro Chromium builds) or is missing a runtime shared library is downgraded from `ok` to `warning`, carrying a remedy: run `vigolium doctor --fix --only chrome` to download a working Chrome for Testing, or point `spidering.browser_path` at a working browser. The server `GET /api/diagnostics` endpoint leaves this heavy probe **off** to stay a cheap, poll-safe readout.
</Note>

### CLI Equivalent

The same checks are available via the CLI without a running server:

```bash theme={null}
# Colored console output
vigolium doctor

# JSON output
vigolium doctor --json
```

The CLI version omits the `queue` check since the queue is only available when the server is running.