Running health checks

Overview

A health check analyses a connection's synced configuration snapshot, runs a suite of checks against it, and produces a scored report with individual findings. Each finding is categorised by severity (critical, warning, or info) and includes details about the specific configuration issue detected, along with the affected object.

Reports include an overall health score, finding counts broken down by severity, and comparison metrics (newFindings and resolvedFindings) relative to the previous report. Health check reports are persistent. Once generated, they can be retrieved by ID, compared over time through the history endpoint, or downloaded as a formatted PDF.

Run a new check

Trigger a health check synchronously. The request loads the most recent snapshot for the connection, runs every applicable check, persists the report, and returns the full result. Both READ_ONLY and READ_WRITE keys are accepted because running a check does not modify your Zendesk instance.

curl -X POST https://api.configly.app/v1/connections/{connectionId}/health-check \
  -H "Authorization: Bearer cly_your_key"

If no configuration snapshot exists for the connection (for example, if a sync has never completed), the endpoint returns 409 with the error code NO_SNAPSHOT. Run a sync first, then retry the health check.

The response wraps the full report in the standard data envelope:

{
  "data": {
    "reportId": "clx9abc123def456",
    "score": 72,
    "totalFindings": 14,
    "criticalCount": 2,
    "warningCount": 7,
    "infoCount": 5,
    "newFindings": 3,
    "resolvedFindings": 1,
    "previousReportId": "clx8xyz789ghi012",
    "findings": [ ... ],
    "triggerType": "api",
    "checkVersion": "1.0.0",
    "aiSummary": null,
    "createdAt": "2026-04-16T09:30:00.000Z"
  }
}

Get latest report

Retrieve the most recent health check report for a connection. Returns the full report including all visible findings. This is a convenient shortcut when you only need the current state rather than a specific historical report.

curl https://api.configly.app/v1/connections/{connectionId}/health-check/latest \
  -H "Authorization: Bearer cly_your_key"

Returns 404 if no reports exist for the connection.

Report history

List health check reports for a connection in reverse chronological order. The response is paginated and includes scores and finding counts only (the findings array is omitted). Use the reportId from each entry to fetch the full report.

curl "https://api.configly.app/v1/connections/{connectionId}/health-check/history?page=1&limit=20" \
  -H "Authorization: Bearer cly_your_key"

Each history entry contains: reportId, score, totalFindings, criticalCount, warningCount, infoCount, triggerType, checkVersion, and createdAt.

Get a specific report

Fetch a single report by its ID. Returns the full report including findings.

curl https://api.configly.app/v1/connections/{connectionId}/health-check/{reportId} \
  -H "Authorization: Bearer cly_your_key"

Returns 404 if the report does not exist or does not belong to the specified connection. Reports are scoped to their connection, so you cannot fetch a report from one connection using another connection's URL path.

Report shape

Error codes

For PDF downloads, see Health check PDF reports.