hosting
POST /v1/sites/{siteId}/vitals/checks
Measure one page of this site on demand.
Xác thực
Gửi khóa API dưới dạng mã thông báo bearer. Điểm cuối này không nêu rõ quyền cụ thể trong thông số kỹ thuật, vì vậy hãy cấp cho khóa của bạn quyền tối thiểu cần thiết và kiểm tra phản hồi thay vì phỏng đoán.
Endpoint này không nhận ID tổ chức. Khóa của bạn đã xác định tổ chức mà nó thuộc về và phản hồi được giới hạn trong phạm vi đó.
Dùng thử
Thay thế bất kỳ nội dung nào trong ngoعل (angle brackets) bằng giá trị của riêng bạn và trình giữ chỗ key bằng một key từ trang tổng quan của bạn.
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> }'Đã đăng nhập? Bảng điều khiển API trong trang quản lý của bạn sẽ tự điền ID tổ chức thực tế và khóa của riêng bạn, sau đó chạy yêu cầu đối với API trực tiếp để bạn có thể xem phản hồi thực tế. Mở điểm cuối này trong bảng điều khiển API
Chi tiết
`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.
Tham số
| Tên | Loại | Bắt buộc | Nội dung này là gì |
|---|---|---|---|
siteId (path) | Uuid | Có | Site ID (UUIDv7). |
Nội dung yêu cầu
| Tên | Loại | Bắt buộc | Nội dung này là gì |
|---|---|---|---|
url | string | Có | 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… |
Phản hồi
| Tên | Loại | Bắt buộc | Nội dung này là gì |
|---|---|---|---|
id | string | Có | — |
url | string | Có | The normalised absolute URL that was (or is being) measured. |
status | string<queued, running, done, failed> | Có | `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 | Có | 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 | Có | 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 | Có | 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 | Có | — |
finished_at | string | Không | — |
result | SiteVitals | Không | 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 | Có | 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… |
Các lỗi điểm cuối này có thể trả về
401 · 403 · 404 · 422 · 429 · 503