hosting
POST /v1/sites/{siteId}/vitals/checks
Measure one page of this site on demand.
Pengesahan
Hantar kunci API sebagai token pembawa. Titik akhir ini tidak menyatakan kebenaran tertentu dalam spesifikasi, jadi berikan kunci anda kebenaran minimum yang diperlukan dan semak respons tersebut daripada membuat andaian.
Titik akhir ini tidak memerlukan id organisasi. Kunci anda telah mengenal pasti organisasi kepunyaannya, dan respons dis skopkan kepadanya.
Cuba
Gantikan apa sahaja di dalam kurungan sudut dengan nilai anda sendiri, dan pemegang tempat kunci dengan kunci dari papan pemuka anda.
curl -X POST https://api.zinndigital.com/v1/sites/{siteId}/vitals/checks \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "url": <string> }'Sudah log masuk? Konsol API dalam papan pemuka anda mengisi id organisasi sebenar dan kunci anda sendiri, serta menjalankan permintaan terhadap API langsung supaya anda boleh melihat respons sebenar. Buka penamat ini dalam konsol API
Butiran
`getSiteVitals` measures the **homepage** on a schedule, which makes the product descriptive. This makes it diagnostic: *"the homepage is fine, it is `/shop/category/boots` that is slow"*. Gated on `sites.view` — asking how fast your own page is changes nothing about it. **Returns `202`, never the measurement.** A Lighthouse run takes 10-30 seconds; holding the request open is the uncached hot-path work CLAUDE.md 2.16 forbids and it times out behind Cloudflare. Poll `getSiteVitalsCheck` with the returned `id` until `status` is `done` or `failed`. **A URL outside this site is a `404`, not a `403`.** A 403 would confirm that some other organisation owns that hostname, turning this endpoint into an ownership oracle over the estate. The submitted address may be a path (`/shop/boots`), a bare hostname, or an absolute URL; it is normalised — lowercased, port and trailing dot stripped, leading `www.` folded — before being compared against the site's `primary_domain` and its aliases. The URL that comes back is rebuilt on whichever of the site's own hostnames matched, **not** on the folded form and not on what was typed: a site that lives on `www.` is measured on `www.`, because the apex may 301 or not resolve at all. Clients should display the returned `url`. **A recent identical check is returned instead of starting a new one.** Within the cache window the stored measurement comes back with `cached: true` and `status` already `done`, and it costs no quota. Clients should render `measured_at` rather than implying the page was just re-measured. **A check of the same URL that is still running is returned too** — same `202`, `cached: false`, `status` `queued` or `running`. A double-click is therefore one measurement and one quota unit, not two. Clients get an `id` to poll either way, so no branch on this is needed; it is documented because the `id` may be one the caller has already seen. **A check that has not finished within the staleness window is reported `failed`** with `error_code: timed_out`, by the read path rather than by a writer. Nothing writes a terminal status when a workflow is cancelled or its task queue has no worker, so a client that waits for one would poll a `running` check for ever. **`429` when the organisation's daily allowance is spent**, with `Retry-After` and a body naming the limit. The allowance exists because one customer in a refresh loop would otherwise burn the whole estate's shared PageSpeed quota and take a free feature down for everyone. Cached results never count against it.
Parameter
| Nama | Jenis | Diperlukan | Apakah ia |
|---|---|---|---|
siteId (path) | Uuid | Ya | Site ID (UUIDv7). |
Badan permintaan
| Nama | Jenis | Diperlukan | Apakah ia |
|---|---|---|---|
url | string | Ya | The page to measure. A path (`/shop/boots`), a bare hostname, or an absolute URL. It must resolve to this site's `primary_domain` or one of its aliases — anything else is a `404… |
Respons
| Nama | Jenis | Diperlukan | Apakah ia |
|---|---|---|---|
id | string | Ya | — |
url | string | Ya | The normalised absolute URL that was (or is being) measured. |
status | string<queued, running, done, failed> | Ya | `failed` is a finished state with a customer-readable `error`, not an infrastructure fault — a page that is down or blocked to crawlers reaches it. |
cached | boolean | Ya | True when this is a stored measurement of the same URL served from the cache window rather than a run that was just started. Render `measured_at` rather than implying the page w… |
error | string | Ya | Empty unless `status` is `failed`. A sentence written for a customer to act on; never a stack trace or an internal hostname. **English, and a FALLBACK** — it is authored server-… |
error_code | string | Ya | A stable machine reason the client turns into a localised sentence: `no_data`, `no_result`, `check_failed`, `timed_out`. Empty unless `status` is `failed`. New members are addit… |
created_at | string | Ya | — |
finished_at | string | Tidak | — |
result | SiteVitals | Tidak | The measurement, present once `status` is `done`. Null while queued or running and on failure — never a zeroed placeholder, which would render as a real measurement of a page th… |
remaining_today | object | Ya | Checks left in this organisation's rolling daily allowance, so the UI can warn before the button is refused rather than only explaining a `429` afterwards. **`null` means no cap… |
Ralat yang boleh dikembalikan oleh titik akhir ini
401 · 403 · 404 · 422 · 429 · 503