# Cloudflare endpoints

> Read the Cloudflare zones, DNS records, WAF rules, audit logs and analytics Vigilbase manages for you, and run the Cloudflare Checkup, over the One API.

Source: https://docs.vigilbase.com/one/api/cloudflare

These endpoints read the Cloudflare accounts and zones linked to your Vigilbase Cloudflare service, and run the [Cloudflare Checkup](https://docs.vigilbase.com/one/services/cloudflare). The CLI's `vigilbase cf` commands use them. Sign-in, permissions, rate limits and error shapes are on [Vigilbase One API](https://docs.vigilbase.com/one/api).

These are v1 operations, on `https://api.vigilbase.com/one/v1`:

| Method and path | Permission | Customer ID | CLI command |
| --- | --- | --- | --- |
| `GET /customers/{customerId}/cloudflare-zones` | `read:services` | In the path | |
| `GET /cloudflare/zones/{zoneId}/dns-records` | `read:services` | Required `customerId` | `vigilbase cf dns <zone-id>` |
| `GET /cloudflare/zones/{zoneId}/security` | `read:services` | Required `customerId` | |
| `GET /cloudflare/checkups` | `read:services` | Optional `customerId`, your own only | `vigilbase cf checkup` |

These have no v1 operation yet, and are on `https://one.vigilbase.com`:

| Method and path | Permission | Customer ID | CLI command |
| --- | --- | --- | --- |
| `GET /api/account/cloudflare/zones` | `read:services` | None | `vigilbase cf zones` |
| `GET /api/services/cloudflare/workspace` | `read:services` | Optional `customerId`, your own only | `vigilbase cf workspace`, `cf accounts` |
| `GET /api/services/cloudflare/workspace/{section}` | `read:services` | Optional `customerId`, your own only | `vigilbase cf workspace <section>` |
| `GET /api/services/cloudflare/zones/{zoneId}/waf` | `read:services` | Required `customerId` | `vigilbase cf waf <zone-id>` |
| `GET /api/customers/{customerId}/cloudflare/zones/{zoneId}` | `read:services` | In the path | `vigilbase cf zone <zone-id> --customer-id …` |
| `GET /api/cloudflare/accounts/{accountId}/audit-logs` | `read:services` | Required `customerId` | `vigilbase cf audit-logs <account-id>` |
| `GET /api/services/cloudflare/analytics` | `read:services` | Required `customerId` | `vigilbase cf analytics` |
| `POST /api/services/cloudflare/checkups/start` | `write:services` and a recent sign-in | Optional `customerId`, your own only | `vigilbase cf checkup start` |
| `GET /api/services/cloudflare/checkups/progress` | `read:services` | None | `vigilbase cf checkup progress <run-id>` |

Account and zone IDs are Cloudflare's 32-character hexadecimal IDs. Customer IDs are UUIDs; `GET /api/account` returns yours as `customer.id`.

Where a customer ID is required, every caller must send one, including for their own customer. A partner organisation can send the ID of a customer it manages on the zone, DNS, security, WAF, audit log and analytics endpoints. The workspace and Checkup endpoints accept only your own customer.

A zone or account must belong to a Cloudflare service of that customer that is active or in trial. Otherwise One answers `403` (`Cloudflare zone is not linked to this customer`, or the account equivalent). A zone One doesn't know answers `404`.

v1 lists are [cursor pages](https://docs.vigilbase.com/one/api#pagination), and their times are ISO 8601 strings.

Some CLI commands, such as `cf speed-settings`, `cf zero-trust`, `cf developer-platform` and `cf magic-transit`, read data reserved for Vigilbase staff; customer sign-ins get `403`.

## Zones

`GET /customers/{customerId}/cloudflare-zones` lists the zones of every Cloudflare account linked to the customer, limited to the zones its services cover. One reads them live from Cloudflare when it can, otherwise from its last sync. Each zone has `id`, `name`, `status`, `paused`, `type` (`full` or `partial`), `developmentMode`, `planName`, `nameServers`, `accountId`, `accountName`, `createdAt`, `activatedAt` and `modifiedAt`. Plan prices aren't included.

`GET /api/account/cloudflare/zones` lists the zones of your own Cloudflare services, from One's records:

```json
{
  "success": true,
  "customer": { "id": "…", "name": "…", "domain": "…", "status": "customer", "isPartner": false },
  "zones": [ { "id": "…", "name": "example.com", "status": "active", "paused": false, "planName": "…" } ],
  "source": "database"
}
```

`GET /api/customers/{customerId}/cloudflare/zones/{zoneId}` reads one zone live from Cloudflare. `data` has `id`, `name`, `status`, `paused`, `type`, `development_mode`, `name_servers`, `original_name_servers`, `plan` and `account`. It answers `404` when Cloudflare doesn't return the zone.

## Workspace

`GET /api/services/cloudflare/workspace` returns what the Cloudflare workspace in One shows: your customer, the service, the linked `accounts` (each with `id`, `name`, `type`, `status`, `zoneCount`), the navigation and the current selection.

| Parameter | Description |
| --- | --- |
| `customerId` | Your own customer ID; any other answers `403` |
| `account` | Select a Cloudflare account ID |
| `zone` | Select a zone ID |
| `variant` | `shield` for a Cloudflare Shield service; anything else, or nothing, selects the Enterprise service |

Add a section to the path for one part of the workspace: `overview`, `reports`, `zones` or `rule-analyzer`. `overview` has summary counts and the five latest reports; `reports` lists up to 24 reports; `zones` lists zones, filtered by `account`. An unknown section, or one your sign-in can't open, answers `404`.

## DNS, security and WAF

`GET /cloudflare/zones/{zoneId}/dns-records?customerId=…` lists the zone's DNS records, read live from Cloudflare. Each record has `id`, `name`, `type`, `content`, `ttl` (seconds; `1` means automatic), `priority`, `proxied`, `proxiable`, `locked`, `createdAt` and `modifiedAt`.

`GET /cloudflare/zones/{zoneId}/security?customerId=…` returns the zone's security defaults, read live from Cloudflare and graded by the Cloudflare Checkup's checks:

| Field | Contents |
| --- | --- |
| `settings` | `ssl`, `waf`, `browserCheck`, `challengeTtl`, `securityLevel`, `opportunisticEncryption`, `automaticHttpsRewrites` and `alwaysUseHttps`, each with `enabled`, `status` (`pass`, `warning`, `fail`, …), `details`, `source`, `value` and `checkedAt` |
| `defaults` | `applied`, whether the zone has every recommended default, and `pending`, the settings still to change |
| `source`, `readAt` | `live` or `checkup`, and when it was read |
| `liveError` | Why Cloudflare couldn't be read live; the settings then come from the latest checkup |
| `checkup` | The checkup the settings come from (`toolRunId`, `checkedAt`), or `null` |

`GET /api/services/cloudflare/zones/{zoneId}/waf?customerId=…` reads the zone's WAF rules live from Cloudflare:

| Field in `data` | Contents |
| --- | --- |
| `rules` | Each rule's `id`, `description`, `action`, `priority`, `paused`, `filter` (with its `expression`), `phase`, `hits_last_30_days` and `last_triggered` |
| `unusedRules` | Active rules with no hits in the last 30 days; empty when hit counts aren't available |
| `suggestions` | Recommendations, each with `category`, `severity`, `title`, `description` and `recommendation` |
| `analyticsAvailable` | Whether hit counts could be read |

When Cloudflare refuses the WAF read, the WAF endpoint still answers `200`, with empty lists.

## Audit logs

`GET /api/cloudflare/accounts/{accountId}/audit-logs?customerId=…` reads up to the 100 most recent Cloudflare audit log entries for the account, live, as `data.logs`. Each entry has `id`, `action`, `actor`, `resource`, `when` and `metadata`. When Cloudflare refuses the read, `logs` is empty.

## Analytics

`GET /api/services/cloudflare/analytics` returns traffic for a customer, an account or a zone.

| Parameter | Description |
| --- | --- |
| `customerId` | Required |
| `accountId` | Optional; one account |
| `zoneId` | Optional; one zone |
| `days` | 1 to 30; default 7 |

One answers from the daily usage it has stored for the customer's active services, as `data.bandwidth`: one entry per day and zone with `date`, `bytes_sent`, `bytes_received`, `requests`, `cached_requests`, `uncached_requests`, `ssl_requests` and `zone_id`.

When nothing is stored and you named an account or zone, One reads Cloudflare live and returns `data.analytics` with `totals` (requests, bandwidth, threats, page views, unique visitors), `cache_ratio`, `threat_ratio` and a `timeseries`. A live zone read always covers the most recent 23 hours, whatever `days` says. When no data is available at all, `analytics` comes back with zero totals.

## Cloudflare Checkup

### Latest checkup

`GET /cloudflare/checkups` returns the latest checkup for your Cloudflare account. When several accounts are linked and One can't tell which you mean, it answers `400` and asks for `accountId`.

| Field | Contents |
| --- | --- |
| `requiresSetup` | `true` when no account can be checked yet; the other fields are then `null` |
| `account` | The account: `id`, `name`, `status` and `scope` (`type`, `account` or `zones`, and `zoneIds`) |
| `credentialSource` | Whose Cloudflare credentials the checkup uses: `default`, `customer` or `partner` |
| `latestRun` | The latest completed run: `id`, `status`, `grade`, `gradeScore`, `createdAt`, `completedAt` |
| `activeRun` | A run in progress (`id`, `status`, `createdAt`, `startedAt`), or `null` |
| `lastValidatedAt` | When the credentials were last validated |

The run's results are at [`GET /tool-runs/{runId}`](https://docs.vigilbase.com/one/api/tool-runs#get-a-run).

### Start a checkup

`POST /api/services/cloudflare/checkups/start` starts a checkup in the background. It needs `write:services` (owners and admins) and a [sign-in from the last 10 minutes](https://docs.vigilbase.com/one/api#changes-that-need-a-recent-sign-in).

```json
{ "accountId": "0123456789abcdef0123456789abcdef" }
```

The body is optional; `accountId` picks the account when several are linked. One answers `202`:

```json
{ "success": true, "data": { "toolRunId": "8d0f…", "status": "running" } }
```

If a checkup of that account is already running, you get that run, with `"reused": true`, instead of a second one.

| Status | When |
| --- | --- |
| `400` | One can't tell which linked account you mean (send `accountId`), or the body is invalid |
| `403` | The account can't be checked, or `customerId` isn't your own |
| `404` | Checkups aren't set up for your organisation |
| `503` | The checkup couldn't start; the run is marked failed. Retry |

### Follow a checkup

`GET /api/services/cloudflare/checkups/progress?toolRunId=…` returns the run's progress events. Pass `since` with the last `seq` you saw to get only newer events.

```json
{
  "success": true,
  "data": {
    "events": [ { "seq": 1, "type": "…", "level": "info", "message": "…", "metadata": { }, "createdAt": "…" } ],
    "latestSeq": 1,
    "status": "running",
    "progressPct": 10,
    "errorMessage": null
  }
}
```

When the run has completed, `data.result` holds the result. The full run, as `vigilbase cf checkup result <run-id>` shows it, is at [`GET /tool-runs/{runId}`](https://docs.vigilbase.com/one/api/tool-runs#get-a-run).

## Older paths

Each v1 operation here also answers at an older path on `https://one.vigilbase.com/api`, such as `GET /api/services/cloudflare/zones/{zoneId}/dns` for `GET /cloudflare/zones/{zoneId}/dns-records`. The older paths are deprecated aliases and will be retired with `410 Gone`. Each operation's page in the [API reference](https://docs.vigilbase.com/one/api/reference) names its older path. See [hosts](https://docs.vigilbase.com/one/api#hosts).