131 lines
6.8 KiB
Markdown
131 lines
6.8 KiB
Markdown
# API Reference
|
|
|
|
This document lists the public ComfyUI-Doctor HTTP endpoints. Exact response payloads can evolve, but the endpoint roles and admin-guard expectations are stable public behavior.
|
|
|
|
Machine-readable contract: [`openapi.json`](openapi.json).
|
|
|
|
## Route Forms and Host Aliases
|
|
|
|
The canonical Doctor route form is `/doctor/...`. Current ComfyUI hosts may also expose `/api/doctor/...` as a host-provided alias where ComfyUI route duplication applies.
|
|
|
|
Doctor documentation and examples use canonical `/doctor/...` paths. Clients running inside a current ComfyUI host may use `/api/doctor/...` when their integration layer expects the host API prefix, but Doctor does not own ComfyUI's global alias behavior.
|
|
|
|
## Prompt Usage-Source Policy
|
|
|
|
Doctor does not currently queue host prompts directly. If a future Doctor feature queues a host prompt, it should identify itself only with a non-secret source string such as `comfyui-doctor`.
|
|
|
|
Usage-source metadata must not include secrets, raw prompts, private paths, cookies, credentials, tokens, API keys, private URLs, or equivalent sensitive material.
|
|
|
|
## Admin-Gated Writes
|
|
|
|
Write-sensitive endpoints require admin authorization unless desktop loopback convenience mode applies. For shared servers, configure `DOCTOR_ADMIN_TOKEN` and `DOCTOR_REQUIRE_ADMIN_TOKEN=1`.
|
|
|
|
JSON error responses use a consistent envelope:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "machine_or_legacy_error_text",
|
|
"message": "Human-readable error message"
|
|
}
|
|
```
|
|
|
|
Some endpoint-specific failure payloads may include additional fields such as `models`, `is_local`, `field_errors`, or `statistics`; existing success payloads keep their documented shapes.
|
|
|
|
Denied writes use:
|
|
|
|
- `401` for missing or invalid token authorization.
|
|
- `403` for policy-denied remote administration.
|
|
|
|
## Debugger Endpoints
|
|
|
|
| Method | Path | Purpose |
|
|
| --- | --- | --- |
|
|
| `GET` | `/debugger/last_analysis` | Return current Doctor status, latest error, suggestion, language, and node context when available. |
|
|
| `GET` | `/debugger/history` | Return recent error-analysis history. |
|
|
| `POST` | `/debugger/set_language` | Change the suggestion language. |
|
|
| `POST` | `/debugger/clear_history` | Clear recorded error history. |
|
|
|
|
## LLM and Chat Endpoints
|
|
|
|
Doctor normalizes provider-specific behavior for OpenAI-compatible APIs, Anthropic, and Ollama behind a shared backend adapter layer. The route endpoints still enforce SSRF checks, credential resolution, privacy sanitization, retry/concurrency limits, and streaming response handling.
|
|
|
|
| Method | Path | Purpose |
|
|
| --- | --- | --- |
|
|
| `GET` | `/doctor/provider_defaults` | Return provider default base URLs. |
|
|
| `POST` | `/doctor/analyze` | Run single-shot LLM analysis for an error context. |
|
|
| `POST` | `/doctor/chat` | Run the interactive chat flow, including SSE streaming when requested. |
|
|
| `POST` | `/doctor/verify_key` | Validate provider connectivity and credential availability. |
|
|
| `POST` | `/doctor/list_models` | List models from the selected provider when supported. |
|
|
| `GET` | `/doctor/ui_text` | Return localized UI text for the frontend. |
|
|
|
|
LLM failure responses use the standard JSON error envelope. The chat streaming path reports stream connection or provider errors as terminal SSE events.
|
|
|
|
## Credential Store Endpoints
|
|
|
|
| Method | Path | Purpose |
|
|
| --- | --- | --- |
|
|
| `GET` | `/doctor/secrets/status` | Return provider credential source status without exposing secret values. |
|
|
| `PUT` | `/doctor/secrets` | Save a provider credential to the optional server-side store. |
|
|
| `DELETE` | `/doctor/secrets/{provider}` | Delete a stored provider credential. |
|
|
|
|
## Statistics, Feedback, and Health Endpoints
|
|
|
|
| Method | Path | Purpose |
|
|
| --- | --- | --- |
|
|
| `GET` | `/doctor/statistics` | Return error statistics for the dashboard. |
|
|
| `POST` | `/doctor/statistics/reset` | Clear statistics/history data. |
|
|
| `POST` | `/doctor/mark_resolved` | Mark the latest matching error as resolved, unresolved, or ignored. |
|
|
| `POST` | `/doctor/feedback/preview` | Build and sanitize a community feedback preview. |
|
|
| `POST` | `/doctor/feedback/submit` | Submit sanitized feedback through the configured GitHub flow. |
|
|
| `GET` | `/doctor/health` | Return Doctor runtime health and path diagnostics. |
|
|
| `GET` | `/doctor/plugins` | Return scan-only plugin trust information. |
|
|
|
|
Path diagnostics in `/doctor/health` report runtime identity separately from
|
|
storage evidence. For example, a managed Desktop runtime can report
|
|
`install_mode=desktop` while `storage_source` identifies ComfyUI's private
|
|
system-user API.
|
|
|
|
## Telemetry Endpoints
|
|
|
|
| Method | Path | Purpose |
|
|
| --- | --- | --- |
|
|
| `GET` | `/doctor/telemetry/status` | Return telemetry enabled/disabled state. |
|
|
| `GET` | `/doctor/telemetry/buffer` | Return local telemetry buffer contents. |
|
|
| `POST` | `/doctor/telemetry/track` | Add a telemetry event when telemetry is enabled. |
|
|
| `POST` | `/doctor/telemetry/clear` | Clear telemetry buffer. |
|
|
| `GET` | `/doctor/telemetry/export` | Export local telemetry buffer. |
|
|
| `POST` | `/doctor/telemetry/toggle` | Enable or disable telemetry. |
|
|
|
|
## Jobs and External Provider Endpoints
|
|
|
|
| Method | Path | Purpose |
|
|
| --- | --- | --- |
|
|
| `GET` | `/doctor/jobs/{job_id}` | Return resumable job state. |
|
|
| `POST` | `/doctor/jobs/{job_id}/resume` | Resume an eligible failed, cancelled, or pending job. |
|
|
| `POST` | `/doctor/jobs/{job_id}/cancel` | Cancel an eligible job. |
|
|
| `GET` | `/doctor/providers/{provider_id}/status` | Return external enrichment provider capability status. |
|
|
|
|
## Diagnostics Endpoints
|
|
|
|
| Method | Path | Purpose |
|
|
| --- | --- | --- |
|
|
| `POST` | `/doctor/health_check` | Run local diagnostics for a workflow/context payload. |
|
|
| `GET` | `/doctor/health_report` | Return the latest diagnostics report. |
|
|
| `GET` | `/doctor/health_history` | Return diagnostics history. |
|
|
| `POST` | `/doctor/health_ack` | Acknowledge, ignore, or resolve diagnostics issues. |
|
|
|
|
Diagnostics reports are produced by concrete local checks such as workflow linting, dependency checks, model asset checks, privacy/security checks, runtime performance checks, and signature-pack checks.
|
|
|
|
Model asset diagnostics use the current host's registered model roots and
|
|
extensions when available, including custom folders and `.pt2`/`.sft`
|
|
artifacts. They also inspect bounded nested subgraph definitions while
|
|
preserving visible-host and concrete source-loader provenance for promoted
|
|
first-party model, image, video, output-image, and audio values. Positional
|
|
widget values remain authoritative and uniquely matched named values are
|
|
fallback only. Input media/caption-pair and registered dataset folders are
|
|
contained without content enumeration. Unknown custom upload-loader semantics
|
|
are not guessed without authoritative node-definition flags. Older hosts
|
|
retain bounded legacy folder fallbacks, and every filesystem candidate must
|
|
remain contained within an authoritative root before it is probed.
|