run_connector_doctor

Verify a project's installation of a connector and ask the connector about every resource it gates — one report, a finding per check.

Purpose

The dashboard's Run Doctor for agents. The installation is verified exactly as verify_connector_installation does it, then the connector is asked about every resource the installation gates, and the answer is one report: a finding for the installation, then one per resource, each with a severity (ok, warning, critical), the connector's own state word, a sentence in the creator's language, whether the creator can fix it and where. A resource the connector has no place for is a warning, never silence. The report is kept on the installation and raises connector.doctor_completed only when the findings differ from the previous run's. The REST twin is POST /v1/projects/{project}/connectors/{key}/installation/doctor.

Required ability

project-connector:update

Input schema

{
  "type": "object",
  "required": ["project_id", "connector"],
  "properties": {
    "project_id": { "type": "string", "description": "UUID of the project." },
    "connector": { "type": "string", "description": "The connector key, as list_connectors returns it." }
  }
}

Output shape

{
  "data": {
    "installation_id": "3b8f0c6e-2d41-4a97-9e5f-1c7d6b2a8e40",
    "connector": "telegram",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "ran_at": "2026-09-12T10:07:00Z",
    "healthy": false,
    "critical": 1,
    "warnings": 0,
    "findings": [
      { "key": "installation", "kind": "installation", "severity": "ok", "severity_label": "OK", "subject": "Research Bot", "state": "connected", "message": "The connector still answers for this installation.", "creator_actionable": false, "fix_url": null, "resource_id": null },
      { "key": "resource:b73c5f21-9d80-4a6e-8215-4f70ce13a9d6", "kind": "resource", "severity": "critical", "severity_label": "Critical", "subject": "Premium Channel", "state": "not_member", "message": "The bot was removed from this channel.", "creator_actionable": true, "fix_url": "https://app.subscriby.net/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/resources", "resource_id": "b73c5f21-9d80-4a6e-8215-4f70ce13a9d6" }
    ]
  },
  "meta": {}
}

Example prompts

"Is Telegram fully working for the Signals project? Check everything, not just the bot."

"Run the doctor on every connector of this project and tell me what needs fixing."

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-connector:update.
RESOURCE_NOT_FOUND — the project is unknown or outside the token's reach.
CONNECTOR_NOT_INSTALLED — the project has no installation of the connector.

verify_connector_installation — the installation alone.
get_connector_installation — the installation with doctor_ran_at and doctor_healthy.
connector.doctor_completed
Connectors API