Lifub API Reference

Version 1.0.3OpenAPI 3.1.0Base URL https://api.lifub.comOpenAPI JSON

Every endpoint below is generated from the same document, so this page and the JSON cannot disagree.

echo

Request echo and fraud detection endpoints

GET `/echo.json`

Echo request details with fraud detection

Returns detailed information about the incoming request including headers, IP address, fingerprint, session hash, and fraud detection signals. Useful for debugging, bot detection, and request inspection. Pass `?status=NNN` to override the default 200 response code (any valid HTTP status 100–999; invalid/absent values fall back to 200).

Responses
Status	Content	Description
200	`application/json` Echo	Echo response with request details
500	—	Internal server error

Example request

curl -sS 'https://api.lifub.com/echo.json'

entropy

Random number generation

GET `/entropy.json`

Generate random entropy values

Returns a collection of random values including UUID, integers, floats, and a Gaussian-distributed number. Uses a fast (non-cryptographic) RNG.

Responses
Status	Content	Description
200	`application/json` EntropyResponse	Entropy values generated successfully
500	—	Internal server error

Example request

curl -sS 'https://api.lifub.com/entropy.json'

encoding

Text encoding utilities (MD5, SHA1, SHA256, Base64)

GET `/encoding.json`

Encode and hash text values

Computes various encodings (Base64, URL) and hashes (MD5, SHA1, SHA256) for the given input value. Also provides octal, decimal, and hex byte representations.

Parameters
Name	In	Type	Required	Description
`value`	query	string	no	Raw input value to encode/decode.
`charset`	query	string	no	Charset name, e.g. `UTF-8`, `ISO-8859-1`, etc. Defaults to `UTF-8` (matching the Kotlin version's `Charsets.UTF_8.name()`).

Responses
Status	Content	Description
200	`application/json` EncodingResponse	Encoding results
500	—	Internal server error

Example request

curl -sS 'https://api.lifub.com/encoding.json'

whois

IP geolocation and WHOIS lookup

GET `/whois.json`

IP geolocation and ASN lookup

Returns GeoIP + ASN data for the caller's IP: country, city, ASN and ISP. Data source: DB-IP Lite (CC BY 4.0). Free-tier responses include the extended fields (`code` postal, `timeZone`, `countryState`, `cityId`, `countryStateId`) in the response shape with sentinel placeholders — contact info@lifub.com to switch a key onto the Pro/Enterprise MaxMind backend that returns real values. This is IP intelligence, NOT RDAP / domain-registration WHOIS. Auth: anonymous callers are rate-limited per IP; authenticated callers pass a key via the `X-API-Key` header, which also governs the monthly quota for that key. The optional `clientId` query parameter is a client-supplied request ID for log correlation; it is NOT used for authentication or billing.

Auth Optional X-API-Key: <API key> - Optional API key. Anonymous callers are rate-limited per IP; a key raises the limit and meters usage.

Parameters
Name	In	Type	Required	Description
`queryIP`	query	string	no	Override IP address for lookup
`clientId`	query	string	no	Optional client-supplied request ID for log correlation. NOT auth.

Responses
Status	Content	Description
200	`application/json` Whois	GeoIP + ASN data for the caller or the overridden IP
429	—	Rate limit or monthly quota exceeded
500	—	Internal server error

Example request

curl -sS 'https://api.lifub.com/whois.json'

inspect

Request inspection utilities

GET `/inspect.json`

Request inspection combined with IP geolocation and ASN

Returns the incoming request (headers, request-body echo, a per-request fingerprint, and ASN-bumped fraud / bot-likelihood signals) combined with GeoIP + ASN data for the caller. Data source: DB-IP Lite (CC BY 4.0); extended geolocation fields (postal, time zone, subdivision) return sentinel placeholders unless the key is on the Pro/Enterprise MaxMind backend. This is IP intelligence, NOT RDAP / domain-registration WHOIS. Auth: anonymous callers are rate-limited per IP; authenticated callers pass a key via the `X-API-Key` header, which also governs the monthly quota for that key. Any tier (Free / Pro / Enterprise) may call this endpoint — plan gating is on quota and extended fields, not on endpoint access. Supports the same optional `queryIP` override and `clientId` log-correlation parameters as `/whois.json`. The debug-only `response-header` parameter echoes caller-specified headers back in the response, restricted to a small allowlist of safe cache / content-negotiation headers.

Auth Optional X-API-Key: <API key> - Optional API key. Anonymous callers are rate-limited per IP; a key raises the limit and meters usage.

Parameters
Name	In	Type	Required	Description
`queryIP`	query	string	no	Override IP address for geolocation lookup
`clientId`	query	string	no	Optional client-supplied request ID for log correlation. NOT auth.
`response-header`	query	string	no	Debug: echo `Name: Value` back as a response header. Restricted to a safe allowlist.

Responses
Status	Content	Description
200	`application/json` Inspection	Inspection data combining request echo and IP geolocation
429	—	Rate limit or monthly quota exceeded
500	—	Internal server error

Example request

curl -sS 'https://api.lifub.com/inspect.json'

curl

HTTP fetch proxy

GET `/curl.json`

HTTP fetch proxycostly

Fetches the specified URL and returns the response status code and body. Targets must be public http/https endpoints; loopback, RFC 1918, link-local, and other non-routable addresses are refused. Response body is capped at 5 MiB.

Parameters
Name	In	Type	Required	Description
`url`	query	string \| null	no	URL to fetch

Responses
Status	Content	Description
200	`application/json` CurlResponse	Successfully fetched URL
400	—	URL missing, malformed, or pointing at a disallowed target
404	—	Failed to fetch URL (network error, etc.)
413	—	Upstream body exceeded the 5 MiB cap
502	—	DNS resolution for the target failed

Example request

curl -sS 'https://api.lifub.com/curl.json'

audit

Bounded HTTP/security and technical SEO site audits

GET `/audit.json`

Audit one page's HTTP/security health and technical SEO readinesscostly

Fetches a public page and a bounded set of same-origin well-known files, plus /llms.txt for the unweighted AI readiness checks; /llms.txt is reported separately under supplementalProbes and never enters probes, coverage, or any score. The page request is repeated once with compression enabled for the advisory performance section, which also reports a single lab timing sample, the negotiated HTTP version, and source-HTML speed signals; it is not a Core Web Vitals measurement and never changes any score, JUnit case, or snapshot diff. When the deployment configures a Chrome UX Report API key, performance.fieldData carries Google's public, aggregated real-user Core Web Vitals at the 75th percentile for the page URL, or for its origin when Google has no record for the URL alone; that lookup sends Google only the URL without its query string or fragment, and if needed its origin, and never fails the audit. Without a key, fieldData.state is notConfigured. The legacy HTTP/security health score and the separately versioned source-HTML technical SEO score have independent opt-in gates; neither is a ranking score. Anonymous callers receive 10 completed reports, then a full one-hour cooldown starts when the tenth report completes. An operator-issued X-Site-Audit-Voucher bearer UUID adds 100 completed reports and bypasses proof-of-work, but not scanner safety limits.

Auth Optional X-Site-Audit-Voucher: <audit voucher> - Operator-issued Site Audit voucher UUID. Optional on GET /audit.json and POST /audit/snapshots, where it adds paid reports and skips the proof of work. Required on GET /audit/quota, which reports the voucher's remaining paid reports. or X-Site-Audit-Trial: <audit trial> - Operator-issued, host-scoped and expiring Site Audit trial. Required on GET /audit/trial and for TLS-only watch creation; optional on GET /audit.json and POST /audit/snapshots, where it reserves the trial's daily report allowance and skips proof of work. Keep this bearer credential out of URLs and logs.

Parameters
Name	In	Type	Required	Description
`url`	query	string \| null	no	Origin/page URL to audit.
`format`	query	string \| null	no	`?format=junit` → JUnit XML instead of JSON (CI-friendly). Any other value (or absent) yields JSON.
`gate`	query	integer \| null (int32)	no	`?gate=N` → a CI gate: respond `422 Unprocessable Entity` when the audit score is below `N` (so `curl --fail` blocks a deploy), else `200`.
`seoGate`	query	integer \| null (int32)	no	`?seoGate=N` → independently gate the complete technical SEO score. Missing, interrupted, or otherwise unscored SEO analysis fails closed.
`expectIndexable`	query	boolean \| null	no	Whether this URL is intended to be indexable. Defaults to `true`; set `expectIndexable=false` for deliberate noindex/excluded pages.
`share`	query	boolean \| null	no	`?share=true` → also publish this completed report under an unguessable id so it can be handed to someone else as a link, and return that id as `shareId`. Off by default: an automated or CI caller stores nothing. Sharing never re-runs the audit and never spends an extra credit.

Responses
Status	Content	Description
200	`application/json` AuditReport `application/xml` string	Audit completed; JUnit XML is returned when format=junit
400	—	URL is missing, malformed, or disallowed by the SSRF policy
402	—	The supplied Site Audit voucher has no paid reports remaining
403	—	The supplied Site Audit voucher is invalid or revoked
409	—	Paid credits exist but are temporarily reserved by audits in progress; retry after the Retry-After interval
422	`application/json` AuditReport `application/xml` string	The requested legacy gate or SEO gate failed
429	—	Free one-hour quota, per-target, or anonymous safety limit exceeded
502	—	Target DNS resolution failed
503	—	The durable Site Audit quota backend is unavailable

Example request

curl -sS 'https://api.lifub.com/audit.json'

GET `/audit/crawl`

Run a bounded sampled site crawlcostly

Unions sitemap, homepage-link, and optional Site Search discovery; reports per-URL provenance, strict bounded sitemap diagnostics, sampled link/site findings, and separate HTTP-health and technical SEO summaries. Coverage is always sampled and resource caps are explicit.

Parameters
Name	In	Type	Required	Description
`url`	query	string \| null	no
`limit`	query	integer \| null	no	Number of pages to audit, clamped to `1..=MAX_PAGES`.
`expectIndexable`	query	boolean \| null	no	Whether sampled pages are intended to be indexable. Defaults to true.

Responses
Status	Content	Description
200	`application/json` CrawlReport	Bounded crawl completed
400	—	URL is missing, malformed, or disallowed by the SSRF policy
429	—	Per-target or anonymous request limit exceeded
502	—	Target DNS resolution failed

Example request

curl -sS 'https://api.lifub.com/audit/crawl'

GET `/audit/diff`

Compare two Site Audit snapshots

Returns legacy URL/health changes plus technical SEO score and stable-check changes only when the SEO analyses are comparable. Optional legacy and SEO-delta gates are independent; format=junit opts into CI output.

Parameters
Name	In	Type	Required	Description
`before`	query	string \| null	no
`after`	query	string \| null	no
`format`	query	string \| null	no	`?format=junit` → JUnit XML instead of JSON (CI-friendly).
`gate`	query	integer \| null (int32)	no	`?gate=N` → a CI gate: respond `422` when the score delta is below `N` (default 0 → any regression fails) or anything `broke`/`disappeared`.
`seoDeltaGate`	query	integer \| null (int32)	no	`?seoDeltaGate=N` → respond `422` when comparable technical SEO score movement is below `N`; unavailable/incomparable SEO fails closed.

Responses
Status	Content	Description
200	`application/json` SnapshotDiff `application/xml` string	Snapshot diff; JUnit XML is returned when format=junit
400	—	Both snapshot IDs are required
404	—	A snapshot was not found
422	`application/json` SnapshotDiff `application/xml` string	A requested legacy or SEO delta gate failed
500	—	Snapshot storage failed

Example request

curl -sS 'https://api.lifub.com/audit/diff'

GET `/audit/quota`

Check a Site Audit voucher's remaining paid reports

Validates the X-Site-Audit-Voucher header and returns how many paid reports the voucher can still start and how many it was issued with. It runs no audit, spends no credit and needs no proof of work. When every remaining credit is reserved by audits in progress, it answers 409 with Retry-After instead of reporting zero.

Auth Requires X-Site-Audit-Voucher: <audit voucher> - Operator-issued Site Audit voucher UUID. Optional on GET /audit.json and POST /audit/snapshots, where it adds paid reports and skips the proof of work. Required on GET /audit/quota, which reports the voucher's remaining paid reports.

Responses
Status	Content	Description
200	`application/json` VoucherQuotaStatus	The voucher's remaining and total paid reports
403	—	The voucher header is missing, or the voucher is invalid or revoked
409	—	Every remaining credit is reserved by audits in progress; retry after the Retry-After interval
429	—	Anonymous request limit exceeded
503	—	The durable Site Audit quota backend is unavailable

Example request

curl -sS 'https://api.lifub.com/audit/quota'

POST `/audit/snapshots`

Capture an immutable Site Audit snapshotcostly

Parameters
Name	In	Type	Required	Description
`url`	query	string \| null	no
`label`	query	string \| null	no
`expectIndexable`	query	boolean \| null	no	Whether this URL is deliberately excluded from search indexing.
`seoGate`	query	integer \| null (int32)	no	Optional technical SEO score gate. Incomplete/unscored analysis fails closed and is not stored as a snapshot.

Responses
Status	Content	Description
201	`application/json` StoredSnapshot	Snapshot captured and stored
400	—	URL is missing, malformed, or disallowed
402	—	The supplied Site Audit voucher has no paid reports remaining
403	—	The supplied Site Audit voucher is invalid or revoked
409	—	Paid credits exist but are temporarily reserved by audits in progress; retry after the Retry-After interval
422	`application/json` AuditReport	The requested technical SEO gate failed; snapshot was not stored
429	—	Free one-hour quota, per-target, or anonymous safety limit exceeded
500	—	Snapshot storage failed
503	—	The durable Site Audit quota backend is unavailable

Example request

curl -sS -X POST 'https://api.lifub.com/audit/snapshots'

GET `/audit/snapshots/{id}`

Fetch a stored Site Audit snapshot

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Snapshot bearer-token ID

Responses
Status	Content	Description
200	`application/json` StoredSnapshot	Stored snapshot
404	—	Snapshot not found
500	—	Snapshot storage failed

Example request

curl -sS 'https://api.lifub.com/audit/snapshots/{id}'

GET `/audit/snapshots/{id}/suite.hurl`

Download a stored Site Audit snapshot as a Hurl assertion suite

Returns the stored report as a re-runnable Hurl file for `hurl --test` or `zforce hurl`. It asserts only what the report recorded - status, final destination, content type, curated header values or presence, the page title, and a lower bound on body size - and never hashes, TLS facts, protocol or timing. Reading it re-runs nothing and spends no credit. The file never contains the snapshot ID.

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Snapshot bearer-token ID

Responses
Status	Content	Description
200	`text/plain` string	The Hurl suite, as an attachment named site-audit-<host>-<yyyymmdd>.hurl
404	—	Snapshot not found
500	—	Snapshot storage or suite generation failed

Example request

curl -sS 'https://api.lifub.com/audit/snapshots/{id}/suite.hurl'

GET `/audit/trial`

Validate complimentary Site Audit access

Auth Requires X-Site-Audit-Trial: <audit trial> - Operator-issued, host-scoped and expiring Site Audit trial. Required on GET /audit/trial and for TLS-only watch creation; optional on GET /audit.json and POST /audit/snapshots, where it reserves the trial's daily report allowance and skips proof of work. Keep this bearer credential out of URLs and logs.

Responses
Status	Content	Description
200	`application/json` TrialStatus
403	—	Invalid, revoked or expired trial
503	—	Trial storage unavailable

Example request

curl -sS 'https://api.lifub.com/audit/trial'

POST `/audit/watches`

Create a scheduled Site Audit watchcostly

Re-audits one URL on a schedule, stores every run as a snapshot, records its legacy compatibility score in a trend, and raises an alert, optionally POSTed to a webhook, when a run regresses: a score drop of at least `threshold`, a first fall below `minimumScore`, an opt-in technical-SEO drop of at least `seoThreshold`, a URL that broke or disappeared, a removed CDN, an unreachable origin, or a certificate close to expiry. The returned `id` is the watch's only credential, and there is no way to list watches. Watches never spend a Site Audit credit. Scheduled runs happen only on deployments that enable the corresponding scheduler; `POST /audit/watches/{id}/run` runs a watch on demand. Default mode `full` preserves the existing report, snapshot and score behavior. Mode `tls` requires an active domain-scoped X-Site-Audit-Trial capability, reserves one of its two TLS watches, and inspects the exact host hourly or less frequently without a full HTTP audit. Expired or revoked trial entitlement stops both scheduled and manual TLS runs.

Auth Optional X-Site-Audit-Trial: <audit trial> - Operator-issued, host-scoped and expiring Site Audit trial. Required on GET /audit/trial and for TLS-only watch creation; optional on GET /audit.json and POST /audit/snapshots, where it reserves the trial's daily report allowance and skips proof of work. Keep this bearer credential out of URLs and logs.

Parameters
Name	In	Type	Required	Description
`mode`	query	null \| WatchMode	no	TLS-only mode requires an active domain-scoped trial. Full is the default.
`url`	query	string \| null	no	The page to watch. A bare host is audited over HTTPS; credentials are stripped, and the same SSRF and web-port checks as `/audit.json` apply.
`label`	query	string \| null	no	Optional free-text label, also stored on every run's snapshot.
`intervalMin`	query	integer \| null (int32)	no	Minutes between scheduled runs. Defaults to 60; clamped to 5..=1440.
`threshold`	query	integer \| null (int32)	no	Alert when the legacy compatibility score drops by at least this many points against the previous run. Defaults to 5; clamped to 1..=100.
`minimumScore`	query	integer \| null (int32)	no	Optional absolute legacy compatibility-score floor (1..=100): alert once when a run first falls below it. Any other value is rejected.
`seoThreshold`	query	integer \| null (int32)	no	Optional technical-SEO drop threshold, clamped to 1..=100. Omitted means the technical-SEO score is not watched.
`webhook`	query	string \| null	no	Optional URL that receives each alert as a JSON POST, which never carries the watch id. Credentials are stripped, and the SSRF and web-port checks apply.

Responses
Status	Content	Description
201	`application/json` AuditWatch	Watch created
400	—	The URL, mode, webhook or minimumScore is missing, malformed, or disallowed
403	—	The TLS trial capability is invalid, expired, revoked, or does not authorize this host
429	—	The global watch capacity or the anonymous request limit is exhausted
500	—	Watch storage failed
503	—	The TLS trial feature or its durable entitlement backend is unavailable

Example request

curl -sS -X POST 'https://api.lifub.com/audit/watches'

GET `/audit/watches/{id}`

Fetch a Site Audit watch

Returns the watch's settings and the outcome of its last run: `lastScore`, `lastRunAt`, and the `baselineSnapshotId` the next run is compared against, which `GET /audit/snapshots/{id}` reads.

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Responses
Status	Content	Description
200	`application/json` AuditWatch	The watch
404	—	Watch not found
429	—	Anonymous request limit exceeded
500	—	Watch storage failed

Example request

curl -sS 'https://api.lifub.com/audit/watches/{id}'

DELETE `/audit/watches/{id}`

Delete a Site Audit watchlive write

Stops the watch and removes its trend and alerts. Snapshots of its earlier runs stay readable until they expire.

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Responses
Status	Content	Description
204	—	Watch deleted
404	—	Watch not found
429	—	Anonymous request limit exceeded
500	—	Watch storage failed

Example request

curl -sS -X DELETE 'https://api.lifub.com/audit/watches/{id}'

GET `/audit/watches/{id}/alerts`

Read a Site Audit watch's regression alerts

The newest 100 alerts at most, newest first. An unknown, deleted or expired watch reads as an empty list, not 404.

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Responses
Status	Content	Description
200	`application/json` array<WatchAlert>	Alerts, newest first
429	—	Anonymous request limit exceeded
500	—	Watch storage failed

Example request

curl -sS 'https://api.lifub.com/audit/watches/{id}/alerts'

GET `/audit/watches/{id}/notifications/email`

Read a watch's notification email status

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Responses
Status	Content	Description
200	`application/json` EmailNotificationStatus	Recipient confirmation and latest delivery receipt
403	—	Trial expired or revoked
404	—	Unknown watch
503	—	Notification store unavailable

Example request

curl -sS 'https://api.lifub.com/audit/watches/{id}/notifications/email'

POST `/audit/watches/{id}/notifications/email`

Request recipient confirmation for watch alertscostly

Sends a 15-minute verification UUID to the requested recipient. Replacing the address disables prior alerts immediately. The response distinguishes SMTP acceptance from a durable queued retry and never returns the verification token.

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Request body — `application/json` *required*
Schema	StartEmailRequest
Example	`{ "email": "string" }`

Responses
Status	Content	Description
202	—	Verification accepted or queued
400	—	Invalid recipient or body
403	—	Trial expired or revoked
404	—	Unknown watch
409	—	Notification configuration changed
429	—	Verification send limit
503	—	Delivery or store unavailable

Example request

curl -sS -X POST 'https://api.lifub.com/audit/watches/{id}/notifications/email'

DELETE `/audit/watches/{id}/notifications/email`

Disable a watch's email notificationslive write

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Responses
Status	Content	Description
204	—	Email channel removed; queued delivery will be cancelled
404	—	Unknown watch
503	—	Store unavailable

Example request

curl -sS -X DELETE 'https://api.lifub.com/audit/watches/{id}/notifications/email'

POST `/audit/watches/{id}/notifications/email/verify`

Confirm a watch's notification recipientcostly

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Request body — `application/json` *required*
Schema	VerifyEmailRequest
Example	`{ "token": "string" }`

Responses
Status	Content	Description
200	`application/json` EmailNotificationStatus	Recipient confirmed; token consumed
400	—	Invalid, expired or consumed token
403	—	Trial expired or revoked
404	—	Unknown watch
429	—	Confirmation attempt limit
503	—	Store unavailable

Example request

curl -sS -X POST 'https://api.lifub.com/audit/watches/{id}/notifications/email/verify'

POST `/audit/watches/{id}/run`

Run a Site Audit watch nowcostly

Audits the watched URL immediately, stores the run as a snapshot, compares it with the previous run, records any alert and POSTs it to the webhook, then returns the updated watch. An audit that fails is recorded as an `unreachable` alert, not returned as an error. The run spends no Site Audit credit.

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Responses
Status	Content	Description
200	`application/json` AuditWatch	The watch after the run
403	—	The TLS trial entitlement is invalid, expired, revoked, or does not authorize this host
404	—	Watch not found, or deleted while the run was in flight
429	—	Anonymous request limit exceeded
500	—	Watch storage failed
503	—	The TLS trial feature or its durable entitlement backend is unavailable

Example request

curl -sS -X POST 'https://api.lifub.com/audit/watches/{id}/run'

GET `/audit/watches/{id}/tls`

Read a watch's latest TLS inspection

Returns certificate dates, trust and inspection scope from the latest completed run, or null before the first TLS observation. It never performs a new audit or sends a notification.

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Responses
Status	Content	Description
200	`application/json` null \| TlsWatchStatus	Latest TLS observation, or null
404	—	Watch not found
429	—	Anonymous request limit exceeded
500	—	Watch storage failed

Example request

curl -sS 'https://api.lifub.com/audit/watches/{id}/tls'

GET `/audit/watches/{id}/trend`

Read a Site Audit watch's score trend

The newest 2000 runs at most, oldest first, one legacy compatibility score each. An unknown, deleted or expired watch reads as an empty list, not 404.

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Watch bearer-token ID

Responses
Status	Content	Description
200	`application/json` array<TrendSample>	Score samples, oldest first
429	—	Anonymous request limit exceeded
500	—	Watch storage failed

Example request

curl -sS 'https://api.lifub.com/audit/watches/{id}/trend'

test

Test endpoints

GET `/test`

Delayed response test endpoint

Returns a response after an optional delay. Useful for testing timeouts, latency handling, and async behavior. Accepts any HTTP method.

Parameters
Name	In	Type	Required	Description
`timeoutInMs`	query	integer \| null (int64)	no	Delay in milliseconds before responding (defaults to 0)

Responses
Status	Content	Description
200	`text/plain` string	Triggered response after delay

Example request

curl -sS 'https://api.lifub.com/test'

stats

Build and deployment information

GET `/stats.json`

Build + health info

Returns api status, version, build hash, build number, and uptime. No per-client data. For per-key usage, see the authenticated metering APIs.

Responses
Status	Content	Description
200	`application/json` Stats	Build and health info

Example request

curl -sS 'https://api.lifub.com/stats.json'

crawler

Web crawler and site indexing API

POST `/sites/crawl`

Handler for POST /sites/crawl (admin multi-site crawl)costly

Auth Requires Authorization: Bearer <admin secret> - The operator's admin secret.

Parameters
Name	In	Type	Required	Description
`allSitesCrawl`	query	boolean	yes	Force crawl all sites regardless of last crawl time
`isThrottled`	query	boolean	yes	Apply rate limiting
`clearIndex`	query	boolean	yes	Clear index before crawl

Schema SitesCrawlStatus

Example

{
  "sites": [
    {
      "crawled": "string",
      "pageCount": 0,
      "siteId": "00000000-0000-4000-8000-000000000000",
      "siteProfile": {
        "configs": [
          {}
        ],
        "email": "string",
        "id": "00000000-0000-4000-8000-000000000000",
        "secret": "00000000-0000-4000-8000-000000000000"
      }
    }
  ]
}

Responses
Status	Content	Description
200	`application/json` SitesCrawlStatus	Multi-site crawl completed
401	—	Unauthorized - invalid service secret

Example request

curl -sS -X POST 'https://api.lifub.com/sites/crawl?allSitesCrawl={allSitesCrawl}&isThrottled={isThrottled}&clearIndex={clearIndex}'

GET `/sites/crawl/status`

Handler for GET /sites/crawl/status

Auth Requires Authorization: Bearer <admin secret> - The operator's admin secret.

Responses
Status	Content	Description
200	`application/json` SitesCrawlStatus	Crawl status retrieved
401	—	Unauthorized - invalid service secret

Example request

curl -sS 'https://api.lifub.com/sites/crawl/status'

PUT `/sites/crawl/status`

Handler for PUT /sites/crawl/statuslive write

Auth Requires Authorization: Bearer <admin secret> - The operator's admin secret.

Schema SitesCrawlStatus

Example

{
  "sites": [
    {
      "crawled": "string",
      "pageCount": 0,
      "siteId": "00000000-0000-4000-8000-000000000000",
      "siteProfile": {
        "configs": [
          {}
        ],
        "email": "string",
        "id": "00000000-0000-4000-8000-000000000000",
        "secret": "00000000-0000-4000-8000-000000000000"
      }
    }
  ]
}

Responses
Status	Content	Description
200	`application/json` SitesCrawlStatus	Crawl status updated
401	—	Unauthorized - invalid service secret

Example request

curl -sS -X PUT 'https://api.lifub.com/sites/crawl/status'

POST `/sites/{siteId}/crawl`

Handler for POST /sites/{siteId}/crawlcostly

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`url`	query	string	yes	URL to crawl
`email`	query	string	no	Email for notifications
`sitemapsOnly`	query	boolean	yes	Only crawl URLs from sitemap
`allowUrlWithQuery`	query	boolean	yes	Allow URLs with query parameters
`pageBodyCssSelector`	query	string	yes	CSS selector for page body extraction
`maxPages`	query	integer	no	Cap pages crawled this run; clamped to the 500 throttled ceiling (only lowers it)

Responses
Status	Content	Description
200	`application/json` CrawlerJobResult	Crawl completed successfully
404	—	Site not found or invalid credentials
500	—	Crawl failed

Example request

curl -sS -X POST 'https://api.lifub.com/sites/{siteId}/crawl?url={url}&sitemapsOnly={sitemapsOnly}&allowUrlWithQuery={allowUrlWithQuery}&pageBodyCssSelector={pageBodyCssSelector}'

POST `/sites/{siteId}/recrawl`

Handler for POST /sites/{siteId}/recrawlcostly

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`clearIndex`	query	boolean	yes	Clear existing index before recrawl

Responses
Status	Content	Description
200	`application/json` CrawlerJobResult	Recrawl completed successfully
404	—	Site not found or invalid credentials
500	—	Recrawl failed

Example request

curl -sS -X POST 'https://api.lifub.com/sites/{siteId}/recrawl?clearIndex={clearIndex}'

sites

Site management, search, and page operations

POST `/sites`

POST /sites - Create a new sitelive write

Request body — `application/json`
Schema	null \| SiteProfileCreation
Example	`{ "configs": [ { "allowUrlWithQuery": false, "pageBodyCssSelector": "string", "sitemapsOnly": false, "url": "string" } ], "email": "string" }`

Responses
Status	Content	Description
201	`application/json` SiteCreation	Site created
500	—	Internal server error

Example request

curl -sS -X POST 'https://api.lifub.com/sites'

PUT `/sites/flush`

PUT /sites/flush - commit the search index (make recent writes visible)live write

Auth Requires Authorization: Bearer <admin secret> - The operator's admin secret.

Responses
Status	Content	Description
204	—	Indices flushed
400	—	Invalid credentials
503	—	Flush failed

Example request

curl -sS -X PUT 'https://api.lifub.com/sites/flush'

POST `/sites/rss`

POST /sites/rss - Create new site and index RSS feedcostly

Parameters
Name	In	Type	Required	Description
`feedUrl`	query	string	yes	RSS feed URL
`stripHtmlTags`	query	boolean	no	Strip HTML tags from content

Responses
Status	Content	Description
200	`application/json` SiteIndexSummary	Feed indexed
400	—	Invalid feed URL or content

Example request

curl -sS -X POST 'https://api.lifub.com/sites/rss?feedUrl={feedUrl}'

GET `/sites/{siteId}`

GET /sites/{siteId} - Fetch all document IDs for a site

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID

Responses
Status	Content	Description
200	`application/json` array<string>	Document IDs
404	—	No documents found

Example request

curl -sS 'https://api.lifub.com/sites/{siteId}'

DELETE `/sites/{siteId}`

DELETE /sites/{siteId} - Clear all pages for a sitelive write

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID

Responses
Status	Content	Description
200	—	Site cleared
204	—	No content to clear

Example request

curl -sS -X DELETE 'https://api.lifub.com/sites/{siteId}'

GET `/sites/{siteId}/autocomplete`

GET /sites/{siteId}/autocomplete - Autocomplete suggestions

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`query`	query	string	yes	Partial search query

Responses
Status	Content	Description
200	`application/json` Autocomplete	Autocomplete suggestions
400	—	Invalid site ID

Example request

curl -sS 'https://api.lifub.com/sites/{siteId}/autocomplete?query={query}'

GET `/sites/{siteId}/har`

GET /sites/{siteId}/har - Export site pages as HAR 1.2

When real HAR data exists (from crawls after HAR capture was enabled), returns filtered real HTTP metadata. Falls back to synthetic HAR from page content when no real HAR data is available (backward compatibility).

Auth One of Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created. or Authorization: Bearer <admin secret> - The operator's admin secret.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`status`	query	integer (int32)	no	Filter by HTTP status code
`since`	query	string	no	ISO 8601: entries crawled at or after
`before`	query	string	no	ISO 8601: entries crawled before
`url`	query	string	no	URL prefix filter
`minTime`	query	number (double)	no	Minimum response time in ms
`maxTime`	query	number (double)	no	Maximum response time in ms
`contentType`	query	string	no	MIME type filter
`sort`	query	string	no	Sort: time, status, crawledAt; prefix - for desc
`limit`	query	integer	no	Max entries (default 100, max 10000)
`offset`	query	integer	no	Skip first N entries

Responses
Status	Content	Description
200	`application/json`	HAR 1.2 export of crawled pages
403	—	Invalid site secret
404	—	No pages found for site

Example request

curl -sS 'https://api.lifub.com/sites/{siteId}/har'

GET `/sites/{siteId}/pages`

GET /sites/{siteId}/pages - Fetch page by URL

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`url`	query	string	yes	Page URL

Responses
Status	Content	Description
200	`application/json` FetchedPage	Page found
404	—	Page not found

Example request

curl -sS 'https://api.lifub.com/sites/{siteId}/pages?url={url}'

PUT `/sites/{siteId}/pages`

PUT /sites/{siteId}/pages - Add/update page in site indexlive write

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`If-Match`	header	string \| null	no	Optional ETag precondition. Omit for legacy unconditional replacement; use * to require an existing page.

Request body — `application/json` *required*
Schema	SitePageInput
Example	`{ "body": "string", "id": "string", "labels": [ "string" ], "siteId": "00000000-0000-4000-8000-000000000000", "thumbnail": "string", "title": "string", "updated": "string", "url": "string" }`

Responses
Status	Content	Description
200	`application/json` FetchedPage	Page indexed
400	—	Malformed If-Match header or missing URL
404	—	Invalid credentials
412	—	If-Match did not match the current page

Example request

curl -sS -X PUT 'https://api.lifub.com/sites/{siteId}/pages'

DELETE `/sites/{siteId}/pages`

DELETE /sites/{siteId}/pages - Delete page by URLlive write

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`url`	query	string	yes	Page URL

Responses
Status	Content	Description
204	—	Page deleted
404	—	Page not found

Example request

curl -sS -X DELETE 'https://api.lifub.com/sites/{siteId}/pages?url={url}'

PUT `/sites/{siteId}/pages/{pageId}`

PUT /sites/{siteId}/pages/{pageId} - Update existing page by IDlive write

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`pageId`	path	string	yes	Page ID (SHA-256 hash, 64 characters)
`If-Match`	header	string \| null	no	Optional ETag precondition. Omit for legacy unconditional replacement; use * to require an existing page.

Request body — `application/json` *required*
Schema	SitePageInput
Example	`{ "body": "string", "id": "string", "labels": [ "string" ], "siteId": "00000000-0000-4000-8000-000000000000", "thumbnail": "string", "title": "string", "updated": "string", "url": "string" }`

Responses
Status	Content	Description
200	`application/json` FetchedPage	Page updated
400	—	Invalid page ID length or missing URL
404	—	Invalid credentials or page not found
412	—	If-Match did not match the current page

Example request

curl -sS -X PUT 'https://api.lifub.com/sites/{siteId}/pages/{pageId}'

DELETE `/sites/{siteId}/pages/{pageId}`

DELETE /sites/{siteId}/pages/{pageId} - Delete page by IDlive write

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`pageId`	path	string	yes	Page ID

Responses
Status	Content	Description
204	—	Page deleted
404	—	Page not found

Example request

curl -sS -X DELETE 'https://api.lifub.com/sites/{siteId}/pages/{pageId}'

PUT `/sites/{siteId}/pages/{pageId}/backdate`

PUT /sites/{siteId}/pages/{pageId}/backdate?updated=<rfc3339>live write

Admin-only test affordance — see [`SiteState::backdate_page`]. Overwrites a page's `updated` timestamp so the recrawl obsolete-cleanup can be tested against a live deployment. Gated by the service/admin secret (same Bearer token as `/flush`), not a per-site secret.

Auth Requires Authorization: Bearer <admin secret> - The operator's admin secret.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`pageId`	path	string	yes	Page ID
`updated`	query	string	yes	New RFC 3339 `updated` timestamp

Responses
Status	Content	Description
204	—	Page timestamp updated
403	—	Invalid admin credentials
404	—	Page not found

Example request

curl -sS -X PUT 'https://api.lifub.com/sites/{siteId}/pages/{pageId}/backdate?updated={updated}'

GET `/sites/{siteId}/profile`

GET /sites/{siteId}/profile - Fetch site profile

Auth One of Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created. or Authorization: Bearer <admin secret> - The operator's admin secret.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID

Responses
Status	Content	Description
200	`application/json` SiteProfile	Profile found
404	—	Profile not found

Example request

curl -sS 'https://api.lifub.com/sites/{siteId}/profile'

PUT `/sites/{siteId}/profile`

PUT /sites/{siteId}/profile - Update site profilelive write

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID

Request body — `application/json` *required*
Schema	SiteProfileUpdate
Example	`{ "configs": [ { "allowUrlWithQuery": false, "pageBodyCssSelector": "string", "sitemapsOnly": false, "url": "string" } ], "email": "string", "secret": "00000000-0000-4000-8000-000000000000" }`

Responses
Status	Content	Description
200	`application/json` SiteProfile	Profile updated
404	—	Profile not found

Example request

curl -sS -X PUT 'https://api.lifub.com/sites/{siteId}/profile'

PUT `/sites/{siteId}/rss`

PUT /sites/{siteId}/rss - Index RSS feed into existing sitecostly

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`feedUrl`	query	string	yes	RSS feed URL
`stripHtmlTags`	query	boolean	no	Strip HTML tags from content

Responses
Status	Content	Description
200	`application/json` SiteIndexSummary	Feed indexed
400	—	Invalid feed URL or content
404	—	Site not found or invalid credentials

Example request

curl -sS -X PUT 'https://api.lifub.com/sites/{siteId}/rss?feedUrl={feedUrl}'

GET `/sites/{siteId}/search`

GET /sites/{siteId}/search - Search within a site

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`query`	query	string	yes	Search query

Responses
Status	Content	Description
200	`application/json` SearchResult	Search results
400	—	Invalid site ID

Example request

curl -sS 'https://api.lifub.com/sites/{siteId}/search?query={query}'

PUT `/sites/{siteId}/xml`

PUT /sites/{siteId}/xml - Index generic XML feed into existing sitecostly

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID
`xmlUrl`	query	string	yes	XML feed URL
`stripHtmlTags`	query	boolean	no	Strip HTML tags from content
`clearIndex`	query	boolean	no	Clear existing index before importing

Responses
Status	Content	Description
200	`application/json` SiteIndexSummary	XML indexed
400	—	Invalid XML URL or content
404	—	Site not found or invalid credentials

Example request

curl -sS -X PUT 'https://api.lifub.com/sites/{siteId}/xml?xmlUrl={xmlUrl}'

email

Email notification endpoints

POST `/sites/{siteId}/email/setup-info`

POST /sites/{siteId}/email/setup-info — send setup information email.costly

Bearer-gated by the per-site secret. The pre-Bearer global counter that previously sat in front of this handler was removed: it incremented before credentials were checked, so any three failed requests could disable the endpoint for everyone until process restart. Authentication is the rate limit. Once auth passes, a per-site cooldown ([`EMAIL_COOLDOWN`]) prevents the endpoint from being turned into an outbound spam / mail-bomb vector for the site's owner mailbox — nobody legitimately hits "send me my setup info" more than once per minute. The cooldown is claimed *before* the send rather than after: a transport that fails slowly is exactly when a retrying client would otherwise hammer the mailbox. The address is the one stored on the site profile, never one supplied in the request, so this endpoint cannot be aimed at a third party. `email` is optional in the Getting Started Gadget, so a profile without one is a normal outcome and answers 204, not an error.

Auth Requires Authorization: Bearer <site secret> - The site's secret UUID, issued when the site was created.

Parameters
Name	In	Type	Required	Description
`siteId`	path	string (uuid)	yes	Site ID

Responses
Status	Content	Description
200	—	Email sent successfully
204	—	No email address is registered for this site
404	—	Site not found or invalid credentials
429	—	Cooldown active — retry after Retry-After
503	—	Email delivery is unavailable

Example request

curl -sS -X POST 'https://api.lifub.com/sites/{siteId}/email/setup-info'

pages

Direct page lookup by ID

GET `/pages/{id}`

GET /pages/{id} - Fetch a page by its ID.

This endpoint allows direct page lookup without requiring site credentials. The page ID is a SHA-256 hash of the siteId + URL.

Parameters
Name	In	Type	Required	Description
`id`	path	string	yes	Page ID (SHA-256 hash)

Responses
Status	Content	Description
200	`application/json` FetchedPage	Page found
404	—	Page not found

Example request

curl -sS 'https://api.lifub.com/pages/{id}'

assets

Asset Manager (Beta — subject to change) — physical asset utilization & booking engine

GET `/assets/asset/{assetId}`

Public consumer view of an asset and its bookable windows

Parameters
Name	In	Type	Required	Description
`assetId`	path	string	yes	Shareable asset id

Responses
Status	Content	Description
200	`application/json` AssetView	Asset with availability
404	—	Unknown asset

Example request

curl -sS 'https://api.lifub.com/assets/asset/{assetId}'

GET `/assets/asset/{assetId}/calendar.ics`

Public availability calendar for one asset as iCalendar (.ics)

Parameters
Name	In	Type	Required	Description
`assetId`	path	string	yes	Shareable asset id

Responses
Status	Content	Description
200	`text/calendar`	text/calendar
404	—	Unknown asset

Example request

curl -sS 'https://api.lifub.com/assets/asset/{assetId}/calendar.ics'

POST `/assets/asset/{assetId}/windows/{windowId}/hold`

Tentatively hold a seat that auto-releases after ttlSeconds (atomic, capacity-aware)costly

Parameters
Name	In	Type	Required	Description
`assetId`	path	string	yes	Shareable asset id
`windowId`	path	string	yes	Window to hold a seat on

Request body — `application/json` *required*
Schema	NewHold
Example	`{ "consumer": "string", "fields": {}, "note": "string", "promoCode": "string", "quantity": 0, "ttlSeconds": 0 }`

Responses
Status	Content	Description
201	`application/json` Reservation	Held booking (confirm it with its id before it expires)
400	—	Invalid ttlSeconds
404	—	Unknown asset or window
409	—	No seats left (slot_full)

Example request

curl -sS -X POST 'https://api.lifub.com/assets/asset/{assetId}/windows/{windowId}/hold'

POST `/assets/asset/{assetId}/windows/{windowId}/reserve`

Reserve/book a utilization window (atomic, capacity-aware)costly

Parameters
Name	In	Type	Required	Description
`assetId`	path	string	yes	Shareable asset id
`windowId`	path	string	yes	Window to reserve

Request body — `application/json` *required*
Schema	NewReservation
Example	`{ "consumer": "string", "fields": {}, "note": "string", "promoCode": "string", "quantity": 0 }`

Responses
Status	Content	Description
201	`application/json` Reservation	Booking receipt (id doubles as the cancel capability)
404	—	Unknown asset or window
409	—	No seats left (slot_full)

Example request

curl -sS -X POST 'https://api.lifub.com/assets/asset/{assetId}/windows/{windowId}/reserve'

POST `/assets/asset/{assetId}/windows/{windowId}/waitlist`

Join a window's waitlist; the head is auto-promoted when a seat freescostly

Parameters
Name	In	Type	Required	Description
`assetId`	path	string	yes	Shareable asset id
`windowId`	path	string	yes	Window to queue for

Request body — `application/json` *required*
Schema	NewWaitlist
Example	`{ "consumer": "string", "fields": {}, "note": "string", "quantity": 0 }`

Responses
Status	Content	Description
201	`application/json` WaitlistEntry	Waitlist ticket (id is the leave capability)
404	—	Unknown asset or window
429	—	Waitlist is full

Example request

curl -sS -X POST 'https://api.lifub.com/assets/asset/{assetId}/windows/{windowId}/waitlist'

DELETE `/assets/asset/{assetId}/windows/{windowId}/waitlist/{ticketId}`

Leave a window's waitlist (ticketId is the capability)live write

Parameters
Name	In	Type	Required	Description
`assetId`	path	string	yes	Shareable asset id
`windowId`	path	string	yes	Window the ticket is on
`ticketId`	path	string	yes	Waitlist ticket to remove

Responses
Status	Content	Description
204	—	Left the waitlist
404	—	Unknown ticket

Example request

curl -sS -X DELETE 'https://api.lifub.com/assets/asset/{assetId}/windows/{windowId}/waitlist/{ticketId}'

POST `/assets/owners`

Mint a new ownerId (manager bearer secret) — Betacostly

Responses
Status	Content	Description
201	—	Minted ownerId — `{ "ownerId": "<uuid>" }`

Example request

curl -sS -X POST 'https://api.lifub.com/assets/owners'

GET `/assets/owners/{ownerId}/assets`

List the owner's assets; ?windows=false for a lightweight summary

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`windows`	query	boolean	no	false → metadata + windowCount only (no inlined windows)

Responses
Status	Content	Description
200	`application/json` AssetRowsResponse	Assets (with windows, or summary); delegated responses omit ownerId and Viewer responses omit reservation IDs
404	—	Unknown owner

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/assets'

POST `/assets/owners/{ownerId}/assets`

Create an assetlive write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId

Schema NewAsset

Example

{
  "bookingFields": [
    {
      "key": "string",
      "label": "string",
      "options": [
        "string"
      ],
      "required": false,
      "type": "text"
    }
  ],
  "currency": "string",
  "description": "string",
  "kind": "string",
  "name": "string",
  "policy": {
    "cancelCutoffMinutes": 0,
    "minNoticeMinutes": 0
  },
  "promoCodes": [
    {
      "amount": 0.0,
      "code": "string",
      "kind": "percent",
      "validFrom": 0,
      "validUntil": 0
    }
  ],
  "timezone": "string"
}

Responses
Status	Content	Description
201	`application/json` Asset	Created asset
404	—	Unknown owner

Example request

curl -sS -X POST 'https://api.lifub.com/assets/owners/{ownerId}/assets'

PATCH `/assets/owners/{ownerId}/assets/{assetId}`

Edit an asset's mutable fields in place (only provided fields change)live write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`assetId`	path	string	yes	Asset to edit

Schema UpdateAsset

Example

{
  "bookingFields": [
    {
      "key": "string",
      "label": "string",
      "options": [
        "string"
      ],
      "required": false,
      "type": "text"
    }
  ],
  "currency": "string",
  "description": "string",
  "kind": "string",
  "name": "string",
  "policy": {
    "cancelCutoffMinutes": 0,
    "minNoticeMinutes": 0
  },
  "promoCodes": [
    {
      "amount": 0.0,
      "code": "string",
      "kind": "percent",
      "validFrom": 0,
      "validUntil": 0
    }
  ],
  "timezone": "string"
}

Responses
Status	Content	Description
200	`application/json` Asset	Updated asset
400	—	Invalid field
404	—	Unknown asset

Example request

curl -sS -X PATCH 'https://api.lifub.com/assets/owners/{ownerId}/assets/{assetId}'

DELETE `/assets/owners/{ownerId}/assets/{assetId}`

Delete an asset and all its windowslive write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`assetId`	path	string	yes	Asset to delete

Responses
Status	Content	Description
204	—	Deleted
404	—	Unknown asset

Example request

curl -sS -X DELETE 'https://api.lifub.com/assets/owners/{ownerId}/assets/{assetId}'

POST `/assets/owners/{ownerId}/assets/{assetId}/availability`

Bulk-generate a recurring grid of utilization windowslive write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`assetId`	path	string	yes	Asset the windows belong to

Request body — `application/json` *required*
Schema	NewAvailability
Example	`{ "capacity": 0, "cost": 0.0, "firstStart": 0, "repeatCount": 0, "repeatEveryMinutes": 0, "slotMinutes": 0, "slots": 0 }`

Responses
Status	Content	Description
201	`application/json` AvailabilityResult	Generation result
400	—	Invalid recurrence
404	—	Unknown asset

Example request

curl -sS -X POST 'https://api.lifub.com/assets/owners/{ownerId}/assets/{assetId}/availability'

GET `/assets/owners/{ownerId}/assets/{assetId}/windows`

A page of one asset's windows (owner drill-down)

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`assetId`	path	string	yes	Asset to page windows for
`offset`	query	integer (int32)	no	Start index (default 0)
`limit`	query	integer (int32)	no	Page size (default 200, max 1000)

Responses
Status	Content	Description
200	`application/json` WindowsPageResponse	A page of windows; Viewer responses omit reservation IDs
404	—	Unknown asset

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/assets/{assetId}/windows'

POST `/assets/owners/{ownerId}/assets/{assetId}/windows`

Add a utilization window (time slot with a cost + capacity)live write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`assetId`	path	string	yes	Asset the window belongs to

Request body — `application/json` *required*
Schema	NewWindow
Example	`{ "capacity": 0, "cost": 0.0, "end": 0, "start": 0 }`

Responses
Status	Content	Description
201	`application/json` Window	Created window
404	—	Unknown asset
409	—	Window overlaps an existing one

Example request

curl -sS -X POST 'https://api.lifub.com/assets/owners/{ownerId}/assets/{assetId}/windows'

DELETE `/assets/owners/{ownerId}/assets/{assetId}/windows`

Bulk-delete an asset's windows whose start is in [from, to) (clear a date range)live write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`assetId`	path	string	yes	Asset to clear windows on
`from`	query	integer (int64)	yes	Range start, epoch-ms (inclusive)
`to`	query	integer (int64)	yes	Range end, epoch-ms (exclusive)

Responses
Status	Content	Description
200	`application/json` BulkDeleteResult	Count deleted
400	—	Missing/invalid range
404	—	Unknown asset

Example request

curl -sS -X DELETE 'https://api.lifub.com/assets/owners/{ownerId}/assets/{assetId}/windows?from={from}&to={to}'

PATCH `/assets/owners/{ownerId}/assets/{assetId}/windows/{windowId}`

Edit a window's cost/capacity in place (time range immutable)live write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`assetId`	path	string	yes	Asset the window belongs to
`windowId`	path	string	yes	Window to edit

Request body — `application/json` *required*
Schema	UpdateWindow
Example	`{ "capacity": 0, "cost": 0.0 }`

Responses
Status	Content	Description
200	`application/json` Window	Updated window
400	—	Invalid cost/capacity
404	—	Unknown asset or window
409	—	Capacity below current bookings

Example request

curl -sS -X PATCH 'https://api.lifub.com/assets/owners/{ownerId}/assets/{assetId}/windows/{windowId}'

DELETE `/assets/owners/{ownerId}/assets/{assetId}/windows/{windowId}`

Delete a utilization windowlive write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`assetId`	path	string	yes	Asset the window belongs to
`windowId`	path	string	yes	Window to delete

Responses
Status	Content	Description
204	—	Deleted
404	—	Unknown asset or window

Example request

curl -sS -X DELETE 'https://api.lifub.com/assets/owners/{ownerId}/assets/{assetId}/windows/{windowId}'

GET `/assets/owners/{ownerId}/audit`

The owner's activity log (audit trail), newest first

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId

Responses
Status	Content	Description
200	`application/json` AuditRowsResponse	Audit events; delegated responses omit reservationId and free-form detail
404	—	Unknown owner

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/audit'

GET `/assets/owners/{ownerId}/calendar.ics`

Owner's full schedule as an iCalendar (.ics) feed

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId

Responses
Status	Content	Description
200	`text/calendar`	text/calendar
404	—	Unknown owner

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/calendar.ics'

GET `/assets/owners/{ownerId}/export`

Export the owner's full data snapshot (assets, bookings, members, webhooks) — owner only

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId (root)

Responses
Status	Content	Description
200	`application/json` OwnerExport	Portable snapshot
403	—	Only the owner may export
404	—	Unknown owner

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/export'

POST `/assets/owners/{ownerId}/import`

Import a data snapshot into an empty owner (ids preserved) — owner onlylive write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	A freshly-minted, empty ownerId (root)

Schema OwnerExport

Example

{
  "assets": [
    {
      "asset": {
        "bookingFields": [
          {}
        ],
        "createdAt": 0,
        "currency": "string",
        "description": "string",
        "id": "string",
        "kind": "string",
        "name": "string",
        "ownerId": "string",
        "policy": {},
        "promoCodes": [
          {}
        ],
        "timezone": "string"
      },
      "windowCount": 0,
      "windows": [
        {
          "assetId": "string",
          "capacity": 0,
          "cost": 0.0,
          "end": 0,
          "id": "string",
          "remaining": 0,
          "reservations": [
            {}
          ],
          "start": 0,
          "waitlisted": 0
        }
      ]
    }
  ],
  "exportedAt": 0,
  "members": [
    {
      "createdAt": 0,
      "id": "string",
      "label": "string",
      "role": "owner"
    }
  ],
  "ownerId": "string",
  "version": 0,
  "webhooks": [
    {
      "createdAt": 0,
      "events": [
        "string"
      ],
      "id": "string",
      "url": "string"
    }
  ]
}

Responses
Status	Content	Description
201	`application/json` ImportResult	Import counts
400	—	Invalid snapshot or unsupported export version
403	—	Only the owner may import
404	—	Unknown owner
409	—	Target owner is not empty or a globally keyed id collides

Example request

curl -sS -X POST 'https://api.lifub.com/assets/owners/{ownerId}/import'

GET `/assets/owners/{ownerId}/members`

List the owner's role-scoped member tokens (owner only)

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId (root)

Responses
Status	Content	Description
200	`application/json` array<Member>	Members
403	—	Only the owner may list members
404	—	Unknown owner

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/members'

POST `/assets/owners/{ownerId}/members`

Mint a role-scoped member token (owner only)live write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId (root)

Request body — `application/json` *required*
Schema	NewMember
Example	`{ "label": "string", "role": "string" }`

Responses
Status	Content	Description
201	`application/json` Member	Minted member token (id is the bearer token + revoke handle)
400	—	Invalid role/label
403	—	Only the owner may mint members
404	—	Unknown owner
429	—	Per-owner member limit reached

Example request

curl -sS -X POST 'https://api.lifub.com/assets/owners/{ownerId}/members'

DELETE `/assets/owners/{ownerId}/members/{memberId}`

Revoke a member token (owner only)live write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId (root)
`memberId`	path	string	yes	Member token to revoke

Responses
Status	Content	Description
204	—	Revoked
403	—	Only the owner may revoke members
404	—	Unknown owner or member

Example request

curl -sS -X DELETE 'https://api.lifub.com/assets/owners/{ownerId}/members/{memberId}'

GET `/assets/owners/{ownerId}/report`

Owner utilization + revenue report (aggregation over all assets)

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId

Responses
Status	Content	Description
200	`application/json` OwnerReport	Aggregated report
404	—	Unknown owner

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/report'

GET `/assets/owners/{ownerId}/reservations`

List active bookings across the owner's assets (paginated)

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`offset`	query	integer (int32)	no	Start index (default 0)
`limit`	query	integer (int32)	no	Page size (default 200, max 1000)

Responses
Status	Content	Description
200	`application/json` ReservationRowsResponse	Reservations (page); Viewer responses omit reservation IDs
404	—	Unknown owner

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/reservations'

POST `/assets/owners/{ownerId}/reservations/{reservationId}/cancel`

Owner cancels a booking on one of their assets (frees the seat)live write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`reservationId`	path	string	yes	Booking to cancel

Responses
Status	Content	Description
200	`application/json` Reservation	Cancelled booking
404	—	Unknown reservation

Example request

curl -sS -X POST 'https://api.lifub.com/assets/owners/{ownerId}/reservations/{reservationId}/cancel'

PATCH `/assets/owners/{ownerId}/reservations/{reservationId}/modify`

Owner edits a booking on one of their assets in place (seat quantity, fields, note)live write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId (or a member token)
`reservationId`	path	string	yes	Booking to modify

Request body — `application/json` *required*
Schema	ModifyReservation
Example	`{ "fields": {}, "note": "string", "quantity": 0 }`

Responses
Status	Content	Description
200	`application/json` Reservation	Updated booking
400	—	Invalid quantity/fields/note
404	—	Unknown reservation
409	—	Increase doesn't fit (slot_full) / booking not active

Example request

curl -sS -X PATCH 'https://api.lifub.com/assets/owners/{ownerId}/reservations/{reservationId}/modify'

GET `/assets/owners/{ownerId}/webhooks`

List the owner's registered outbound webhooks

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId

Responses
Status	Content	Description
200	`application/json` array<Webhook>	Registered webhooks
404	—	Unknown owner

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/webhooks'

POST `/assets/owners/{ownerId}/webhooks`

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId

Request body — `application/json` *required*
Schema	NewWebhook
Example	`{ "events": [ "string" ], "url": "string" }`

Responses
Status	Content	Description
201	`application/json` Webhook	Registered webhook (id doubles as the delete capability)
400	—	Invalid or disallowed URL / event
404	—	Unknown owner
429	—	Per-owner webhook limit reached

Example request

curl -sS -X POST 'https://api.lifub.com/assets/owners/{ownerId}/webhooks'

DELETE `/assets/owners/{ownerId}/webhooks/{webhookId}`

Delete a registered webhooklive write

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Manager's secret ownerId
`webhookId`	path	string	yes	Webhook to delete

Responses
Status	Content	Description
204	—	Deleted
404	—	Unknown owner or webhook

Example request

curl -sS -X DELETE 'https://api.lifub.com/assets/owners/{ownerId}/webhooks/{webhookId}'

GET `/assets/owners/{ownerId}/whoami`

Resolve the caller's effective role (owner or a member token)

Auth The ownerId path segment is the owner's bearer secret; treat the URL as a credential.

Parameters
Name	In	Type	Required	Description
`ownerId`	path	string	yes	Owner secret or a member token

Responses
Status	Content	Description
200	`application/json` WhoAmI	Resolved identity
404	—	Unknown owner/member token

Example request

curl -sS 'https://api.lifub.com/assets/owners/{ownerId}/whoami'

POST `/assets/reservations/{reservationId}/cancel`

Consumer cancels their own booking (reservationId is the capability)costly

Parameters
Name	In	Type	Required	Description
`reservationId`	path	string	yes	The booking receipt id

Responses
Status	Content	Description
200	`application/json` Reservation	Cancelled booking
404	—	Unknown reservation

Example request

curl -sS -X POST 'https://api.lifub.com/assets/reservations/{reservationId}/cancel'

POST `/assets/reservations/{reservationId}/confirm`

Promote a held seat to a confirmed booking (reservationId is the capability)costly

Parameters
Name	In	Type	Required	Description
`reservationId`	path	string	yes	The held booking's receipt id

Responses
Status	Content	Description
200	`application/json` Reservation	Confirmed booking
404	—	Unknown reservation
409	—	Hold already expired, or the booking isn't a hold

Example request

curl -sS -X POST 'https://api.lifub.com/assets/reservations/{reservationId}/confirm'

PATCH `/assets/reservations/{reservationId}/modify`

Consumer edits their active booking in place (seat quantity, custom fields, note)costly

Parameters
Name	In	Type	Required	Description
`reservationId`	path	string	yes	The booking receipt id

Request body — `application/json` *required*
Schema	ModifyReservation
Example	`{ "fields": {}, "note": "string", "quantity": 0 }`

Responses
Status	Content	Description
200	`application/json` Reservation	Updated booking
400	—	Invalid quantity/fields/note
404	—	Unknown reservation
409	—	Increase doesn't fit (slot_full) / booking not active

Example request

curl -sS -X PATCH 'https://api.lifub.com/assets/reservations/{reservationId}/modify'

POST `/assets/reservations/{reservationId}/reschedule`

Consumer reschedules their booking onto another window of the same assetcostly

Parameters
Name	In	Type	Required	Description
`reservationId`	path	string	yes	The booking receipt id

Request body — `application/json` *required*
Schema	RescheduleRequest
Example	`{ "windowId": "string" }`

Responses
Status	Content	Description
201	`application/json` Reservation	New booking (fresh reservationId)
404	—	Unknown reservation or target window
409	—	Target full / already cancelled / same window

Example request

curl -sS -X POST 'https://api.lifub.com/assets/reservations/{reservationId}/reschedule'

visit

Visit tracking beacon, Web Vitals, engagement, and per-site analytics

GET `/analytics.js`

Consolidated tracking tag (server record + client collector)live write

Fetched by every client that loads the embed. Records the visit from server-side request fingerprints (IP / JA3 / JA4 / TLS cipher / HTTP protocol / UA / ASN / country) and returns a small collector script that enriches the row with client signals when executed. `siteId` is required to count the visit.

Parameters
Name	In	Type	Required	Description
`siteId`	query	string	no	Site id to count the visit against
`queryIP`	query	string	no	Override IP for the geolocation / ASN lookup
`cookies`	query	boolean	no	Option B: enable the first-party loxal_vid cookie (returning-visitor detection)
`banner`	query	boolean	no	Option B + banner: serve Analytics' own equal-prominence consent UI
`cookieConsent`	query	string	no	Option B2 (`signal`): defer the cookie write until `window.loxalAnalytics.consent('granted')`
`cmp`	query	string	no	Compatibility alias: `external` selects `cookieConsent=signal` (requires `cookies=true`)
`vitals`	query	boolean	no	Opt-in Core Web Vitals collection (LCP / INP / CLS / TTFB), posted to /visit/vitals.json on visibilitychange
`engagement`	query	boolean	no	Opt-in engagement-depth collection (time on page, scroll %, interaction count), posted to /visit/engagement.json on visibilitychange
`outbound`	query	boolean	no	Opt-in outbound-clicks & downloads collection (external <a> hosts, download file extensions), posted to /visit/outbound.json on visibilitychange

Responses
Status	Content	Description
200	—	Collector JavaScript (text/javascript)

Example request

curl -sS 'https://api.lifub.com/analytics.js'

POST `/visit.json`

Visit beacon with bot / AI-agent recognitionlive write

First-party analytics beacon: the tracking tag POSTs the visitor's client runtime signals (all optional) and this fuses them with the server-side IP / ASN / header fraud analysis (shared with /inspect.json) to return a human / suspect / bot verdict for the visit. Anonymous callers are rate-limited per IP; keyed callers are metered against their plan quota — any tier may call it. A missing or malformed body still returns a server-side verdict (a beacon must never hard-fail the host page). Optional `queryIP` overrides the IP used for the geolocation / ASN lookup, mirroring /whois.json and /inspect.json.

Auth Optional X-API-Key: <API key> - Optional API key. Anonymous callers are rate-limited per IP; a key raises the limit and meters usage.

Parameters
Name	In	Type	Required	Description
`queryIP`	query	string	no	Override IP for the geolocation / ASN lookup

Request body — `application/json` *required*
Description	Client runtime signals from the tracking tag (all optional)
Schema	ClientSignals
Example	`{ "hardwareConcurrency": null, "languagesCount": null, "pluginsCount": null, "referrer": null, "url": null, "webdriver": null }`

Responses
Status	Content	Description
200	`application/json` Visit	Visit verdict
429	—	Rate limit or monthly quota exceeded
500	—	Internal server error

Example request

curl -sS -X POST 'https://api.lifub.com/visit.json'

POST `/visit/engagement.json`

Attach engagement depth to a /analytics.js visitlive write

Third step of the /analytics.js tag (JS clients, `?engagement=true` only). POSTs the visit's visible time-on-page, deepest scroll %, and interaction count as a small JSON object; the server merges them into the visit's `meta.engagement`. Never affects the bot / human verdict.

Auth Optional X-API-Key: <API key> - Optional API key. Anonymous callers are rate-limited per IP; a key raises the limit and meters usage.

Parameters
Name	In	Type	Required	Description
`id`	query	string	yes	visit_id issued by GET /analytics.js

Request body — `application/json` *required*
Description	Engagement-depth sample
Schema	PageEngagement
Example	`{ "interactions": null, "scrollPct": null, "timeOnPageMs": null }`

Responses
Status	Content	Description
200	—	Accepted (fire-and-forget)

Example request

curl -sS -X POST 'https://api.lifub.com/visit/engagement.json?id={id}'

POST `/visit/enrich.json`

Enrich a /analytics.js visit with client signalslive write

Second step of the /analytics.js tag (JS clients only). POSTs client runtime signals for the `id` returned by /analytics.js; re-fuses them with the stored server verdict, updates the row, and returns the verdict as JSON.

Auth Optional X-API-Key: <API key> - Optional API key. Anonymous callers are rate-limited per IP; a key raises the limit and meters usage.

Parameters
Name	In	Type	Required	Description
`id`	query	string	yes	visit_id issued by GET /analytics.js

Request body — `application/json` *required*
Description	Client runtime signals
Schema	ClientSignals
Example	`{ "hardwareConcurrency": null, "languagesCount": null, "pluginsCount": null, "referrer": null, "url": null, "webdriver": null }`

Responses
Status	Content	Description
200	—	Verdict (verdict / score / reasons) as JSON

Example request

curl -sS -X POST 'https://api.lifub.com/visit/enrich.json?id={id}'

POST `/visit/outbound.json`

Attach outbound clicks & downloads to a /analytics.js visitlive write

Fourth step of the /analytics.js tag (JS clients, `?outbound=true` only). POSTs a batch of outbound clicks / downloads for the visit (destination hosts and/or download file extensions only — never the raw href, path, query, or fragment); the server merges them into the visit's `meta.outbound`. Never affects the bot / human verdict.

Auth Optional X-API-Key: <API key> - Optional API key. Anonymous callers are rate-limited per IP; a key raises the limit and meters usage.

Parameters
Name	In	Type	Required	Description
`id`	query	string	yes	visit_id issued by GET /analytics.js

Request body — `application/json` *required*
Description	Batched outbound events
Schema	PageOutbound
Example	`{ "events": [ { "downloadExt": null, "host": null } ] }`

Responses
Status	Content	Description
200	—	Accepted (fire-and-forget)

Example request

curl -sS -X POST 'https://api.lifub.com/visit/outbound.json?id={id}'

POST `/visit/retention.json`

Set a site's data-retention TTL (days) — requires siteSecretlive write

Auth Requires ?siteSecret=<site secret> - The site's secret UUID, as a query parameter.

Parameters
Name	In	Type	Required	Description
`siteId`	query	string	yes	Site id (UUID) to configure
`siteSecret`	query	string	yes	The site's write/config secret (UUID)
`days`	query	integer (int64)	yes	Retention in days (>= 1); default 365

Responses
Status	Content	Description
200	—	Updated retention
400	—	Missing/invalid siteId or days
401	—	Missing or invalid siteSecret
503	—	Metering backend temporarily unavailable — retry later (Retry-After)

Example request

curl -sS -X POST 'https://api.lifub.com/visit/retention.json?siteId={siteId}&siteSecret={siteSecret}&days={days}'

GET `/visit/stats.json`

Aggregated visit analytics for a site

Returns visit totals (human / suspect / bot), a per-UTC-day human/bot time series, and top-pages / top-referrers breakdowns for a tracked `siteId`, over the last `days` days (default 7, max 365). `siteId` is a required UUID — the unguessable id is itself the read capability, so no separate token is needed for public sites; a non-UUID `siteId` is rejected. Private sites require a valid `siteSecret`. A verified owner's response additionally includes the current `retentionDays`; the field is absent when ownership or retention cannot be verified.

Auth Optional X-API-Key: <API key> - Optional API key. Anonymous callers are rate-limited per IP; a key raises the limit and meters usage.

Parameters
Name	In	Type	Required	Description
`siteId`	query	string	yes	Site id (UUID) whose analytics to read
`days`	query	integer (int32)	no	Window length in days (default 7, max 365)
`siteSecret`	query	string	no	Owner secret; required for private analytics, otherwise optional for retention readback. Reading never claims an unowned site.

Responses
Status	Content	Description
200	`application/json` VisitStatsResponse	Aggregated visit analytics with owner-only retention when available
400	—	Missing or non-UUID `siteId` parameter
401	—	Private analytics require a valid siteSecret
500	—	Internal server error
503	—	Metering backend unavailable or report capacity busy - retry later (Retry-After: 30)

Example request

curl -sS 'https://api.lifub.com/visit/stats.json?siteId={siteId}'

POST `/visit/visibility.json`

Toggle a site's analytics public/private — requires siteSecretlive write

Auth Requires ?siteSecret=<site secret> - The site's secret UUID, as a query parameter.

Parameters
Name	In	Type	Required	Description
`siteId`	query	string	yes	Site id (UUID) to configure
`siteSecret`	query	string	yes	The site's write/config secret (UUID)
`private`	query	boolean	yes	true = private (stats reads need the siteSecret); false = public

Responses
Status	Content	Description
200	—	Updated visibility
400	—	Missing/invalid siteId or private flag
401	—	Missing or invalid siteSecret
503	—	Metering backend temporarily unavailable — retry later (Retry-After)

Example request

curl -sS -X POST 'https://api.lifub.com/visit/visibility.json?siteId={siteId}&siteSecret={siteSecret}&private={private}'

POST `/visit/vitals.json`

Attach Core Web Vitals to a /analytics.js visitlive write

Third step of the /analytics.js tag (JS clients, `?vitals=true` only). POSTs the visit's Largest Contentful Paint, Interaction to Next Paint, Cumulative Layout Shift, and Time to First Byte as a small JSON object; the server merges them into the visit's `meta.vitals`. Never affects the bot / human verdict.

Auth Optional X-API-Key: <API key> - Optional API key. Anonymous callers are rate-limited per IP; a key raises the limit and meters usage.

Parameters
Name	In	Type	Required	Description
`id`	query	string	yes	visit_id issued by GET /analytics.js

Request body — `application/json` *required*
Description	Core Web Vitals sample
Schema	PageVitals
Example	`{ "cls": null, "inpMs": null, "lcpMs": null, "ttfbMs": null }`

Responses
Status	Content	Description
200	—	Accepted (fire-and-forget)

Example request

curl -sS -X POST 'https://api.lifub.com/visit/vitals.json?id={id}'

admin

Operator-only crawler introspection

GET `/admin/active-crawls`

Handler for GET /admin/active-crawls

Returns the number of in-flight crawls plus the site IDs currently being crawled. Used by the §7.4 migration runbook to poll for `running == 0` after setting `MIGRATION_LOCKDOWN=true`.

Auth Requires Authorization: Bearer <admin secret> - The operator's admin secret.

Responses
Status	Content	Description
200	`application/json` ActiveCrawlsResponse	Active crawl counter
401	—	Unauthorized - invalid admin secret

Example request

curl -sS 'https://api.lifub.com/admin/active-crawls'

GET `/admin/promoted`

Handler for GET /admin/promoted

Reports whether the embedded store's warm-standby writer has been armed (`EmbeddedStore::promote`, see the `api` Deployment `strategy:` comment in `api.yaml`). Unauthenticated by design — a pure operational liveness signal like `/health`, exposing no data. A warm-standby process answers `/health` while still read-only, before it takes the SQLite writer flock. Deployment checks can poll this endpoint so callers never race the promotion window into a raw 500 "attempt to write a readonly database" (`voyk/src/store/embedded/mod.rs::promote`).

Responses
Status	Content	Description
200	—	Writer promoted; the store accepts writes
503	—	Still warm-standby; retry after the given Retry-After

Example request

curl -sS 'https://api.lifub.com/admin/promoted'

Schemas

ActiveCrawlsResponse

Response shape for `GET /admin/active-crawls` (§7.4).

Properties
Name	Type	Required	Description
`running`	integer	yes
`site_ids`	array<string (uuid)>	yes

Used by: GET /admin/active-crawls

AnalyticsStatsSummary

Successful `visit_stats` computes, published on `/stats.json` as `analyticsStats` so the `redis-capacity` CI job can page when the compute time drifts toward STATS_COMPUTE_CEILING - the growth signal that would otherwise end in a permanent 503 (the 2026-09-02 lesson: a warning nobody reads is not detection).

Properties
Name	Type	Required	Description
`days`	integer (int64)	yes	Window of the most recent successful compute, in days.
`lastComputeMs`	integer (int64)	yes	Wall-clock milliseconds of the most recent successful compute.
`lastOkUnixMs`	integer (int64)	yes	Unix milliseconds when that compute finished.
`recentMaxBucketMs`	integer \| null (int64)	no	Resolution of the rolling maximum's fixed-size buckets.
`recentMaxComputeMs`	integer \| null (int64)	no	Largest successful compute in this process's recent minute buckets.
`recentMaxWindowMs`	integer \| null (int64)	no	Requested rolling window. Minute buckets conservatively retain a peak for up to one additional minute; these are per-process, not fleet stats.
`site`	string	yes	Site of the most recent successful compute, not necessarily the recent peak.

Asset

A published asset. `ownerId` is the manager's secret and is only returned to the root manager/export surface, never to delegated or public views.

Properties
Name	Type	Required	Description
`bookingFields`	array<BookingFieldDef>	no	Owner-defined fields a consumer must/may fill when booking (empty = none).
`createdAt`	integer (int64)	yes	Epoch-ms creation time.
`currency`	string	yes	Currency the window costs are quoted in — a free-form symbol or code (`$`, `USD`, `EUR`, `£`, `CHF`, …); not necessarily USD.
`description`	string \| null	no
`id`	string	yes	Unguessable UUID; doubles as the shareable consumer link.
`kind`	string	yes	Free-form category, e.g. `drone`, `court`, `vehicle`, `lesson`, `property`.
`name`	string	yes	Human name, e.g. "Court 1", "DJI Mavic 3", "Grand-piano lesson".
`ownerId`	string	yes	The managing owner's secret UUID.
`policy`	null \| BookingPolicy	no
`promoCodes`	array<PromoCode>	no	Owner-defined discount codes (empty = none). Only ever returned on the manager surface — never leaked on the public [`AssetView`].
`timezone`	string	no	IANA timezone the window times are meant to be read in (e.g. `Europe/Berlin`); defaults to `UTC`. Times on the wire stay epoch-ms UTC — this only drives how a client renders them.

Used by: POST /assets/owners/{ownerId}/assets, PATCH /assets/owners/{ownerId}/assets/{assetId}

AssetRowsResponse

Role-dependent serialization for `GET /owners/{token}/assets`.

Type: array<AssetWithWindows> | array<DelegatedAssetWithWindows> | array<ViewerAssetWithWindows>

Used by: GET /assets/owners/{ownerId}/assets

AssetView

The public consumer view of an asset: descriptive fields + windows, **without** the `ownerId` and without other consumers' booking details.

Properties
Name	Type	Required	Description
`bookingFields`	array<BookingFieldDef>	no	Custom fields the consumer must/may fill when booking (empty = none).
`currency`	string	yes
`description`	string \| null	no
`id`	string	yes
`kind`	string	yes
`name`	string	yes
`timezone`	string	yes	IANA timezone the consumer should read the slots in (default `UTC`).
`windows`	array<PublicWindow>	yes

Used by: GET /assets/asset/{assetId}

AssetWithWindows

Manager view of one asset: the asset plus all its windows (with bookings). In the lightweight summary view (`?windows=false`) `windows` is empty and only `windowCount` is populated — so listing a large catalog doesn't inline every window+booking.

Properties
Name	Type	Required	Description
`asset`	Asset	yes
`windowCount`	integer (int32)	no	Total windows on the asset (always set; the only window info in the summary view).
`windows`	array<Window>	no

AuditAction

One remediation objective backed by the checks that contributed to it.

Properties
Name	Type	Required	Description
`category`	string	no	Report area associated with the highest-severity contributor.
`contributingCheckIds`	array<string>	no	Stable check or finding IDs merged into this action.
`evidence`	array<string>	no	Bounded observations supporting this action.
`id`	string	no	Stable remediation-family identifier, for example `header.csp`.
`recommendation`	string	no	Concrete remediation guidance from the highest-severity contributor.
`severity`	string	no	Highest advisory severity among the contributing checks.
`title`	string	no	Short action label.
`why`	string	no	Why this matters: the objective consequence of leaving it unresolved, never an effort, ownership, or business-impact estimate. Omitted when empty, which is how reports stored before this field existed read.

AuditCoverage

How much of the fixed one-page audit fan-out returned usable response evidence. Coverage is independent of both health scores: a complete report can faithfully describe an unhealthy origin, while consumers can use a partial report to distinguish unevaluated checks from the frozen legacy score and absence-shaped finding contract.

Properties
Name	Type	Required	Description
`auxiliaryResponseReceived`	boolean	no	At least one same-origin auxiliary probe returned an HTTP response. Together with `pageResponseReceived: false`, this fact identifies differential reachability without guessing whether the differentiator was an edge policy, WAF, client fingerprint, IP, or something else.
`complete`	boolean	no	Every scheduled probe returned an HTTP response and a complete body.
`completedProbes`	integer	no	Probes that returned an HTTP response without truncation.
`pageResponseReceived`	boolean	no	The primary page returned an HTTP response, irrespective of its status.
`totalProbes`	integer	no	Probes scheduled for this audit.

AuditEvent

One entry in an owner's activity log (audit trail). Append-only, newest-first, capped at [`AUDIT_MAX`] and TTL'd like the rest of the owner's data.

Properties
Name	Type	Required	Description
`action`	string	yes	Machine-readable action: `owner.create`, `asset.create`, `asset.update`, `asset.delete`, `window.add`, `window.update`, `window.delete`, `availability.generate`, `reserve`, `hold`, `confirm`, `cancel`, `modify`, `webhook.add`, `webhook.delete`, `member.add`, `member.delete`, `waitlist.join`, `waitlist.leave`, `waitlist.promote`, `owner.import`, `window.bulk_delete`.
`assetId`	string \| null	no
`at`	integer (int64)	yes	Epoch-ms when the action happened.
`detail`	string \| null	no	Short human detail (asset name, booker handle, generated counts, …).
`reservationId`	string \| null	no
`windowId`	string \| null	no

AuditProvenance

Compact provenance for a completed one-page report.

Properties
Name	Type	Required	Description
`capturedAt`	integer (int64)	no	Server capture time in Unix epoch milliseconds.
`effectiveOrigin`	string \| null	no	Effective scheme/host/port, only when the page returned HTTP.
`effectiveUrl`	string \| null	no	Final URL observed after redirects, only when the page returned HTTP.
`engineVersion`	string	no	Version of the Site Audit engine that produced the report.
`httpClientProfileId`	string	no	Stable request/client profile used by the fetcher.
`pageEncoding`	null \| PageEncodingProvenance	no
`reportSchemaVersion`	integer (int32)	no	Version of the top-level report wire schema.
`sourceRevision`	string \| null	no	Exact deployed Git revision when a release supplied one.
`vantage`	string \| null	no	Coarse operator-defined capture vantage, never an egress IP or hostname.

AuditReport

Top-level audit report.

Properties
Name	Type	Required	Description
`actions`	array<AuditAction>	no	Deterministic remediation objectives derived from existing findings and failed checks. Additive and independent of every score.
`cdn`	CdnInfo	no
`coverage`	AuditCoverage	no
`findingDetails`	array<FindingDetail>	no	The same findings, in the same order, each carrying a stable catalogue id, a severity, and the what/why/how explanation needed to act on it (see [`explain`]). Additive: `findings` remains the established field, and a snapshot captured before this existed simply deserializes empty.
`findings`	array<string>	no	Notable issues found, human-readable.
`health`	null \| HealthReport	no
`host`	string	no	The normalized host that was audited.
`meta`	null \| PageMeta	no
`performance`	null \| PerformanceReport	no
`probes`	array<ProbeResult>	no	Per-URL results, page first then well-known paths sorted.
`provenance`	null \| AuditProvenance	no
`score`	integer (int32)	no	Legacy HTTP/security health score 0–100. Its established weighting and gate semantics are intentionally independent of the versioned SEO score.
`security`	null \| SecurityAnalysis	no
`seo`	null \| SeoReport	no
`shareId`	string \| null	no	Set when this report was published as a shareable copy (`?share=true`): the unguessable id it is retrievable under at `/audit/snapshots/{shareId}`. Absent means the report was not stored, so nothing about this run is retrievable by anyone else.
`supplementalProbes`	array<ProbeResult>	no	Requests made beside the fixed probe set, currently `/llms.txt` for the AI readiness checks, sorted by path. They are excluded from `probes`, `coverage`, the legacy `score`, `health`, the probe changes of snapshot diffs, watch alerts, and probe JUnit. The `/llms.txt` result feeds only the unweighted `ai-readiness.llms-txt` check, which, like every SEO check, is listed in a snapshot diff's `seoCheckChanges` and in SEO-gate JUnit and never fails either. Omitted when empty, which is how reports captured before they existed read.
`target`	string	no	The audited URL, normalized and with any `user:pass@` credentials stripped (never the raw input — see [`run_audit`]).
`tls`	null \| TlsInfo	no
`tlsInspection`	null \| TlsInspectionEvidence	no
`unicodeHost`	string \| null	no	Unicode presentation form of an IDN host. `host` remains the canonical ASCII/Punycode security and network identity.

Used by: GET /audit.json, POST /audit/snapshots

AuditRowsResponse

Role-dependent serialization for the manager audit trail.

Type: array<AuditEvent> | array<DelegatedAuditEvent>

Used by: GET /assets/owners/{ownerId}/audit

AuditWatch

A scheduled audit watch. The `id` is the bearer secret.

Properties
Name	Type	Required	Description
`baselineSnapshotId`	string \| null	no	The previous run's snapshot id - the baseline the next run diffs against.
`createdAt`	integer (int64)	yes	Creation time, epoch milliseconds.
`id`	string	yes	The watch's bearer secret: anyone holding it can read, run or delete the watch, and there is deliberately no way to list watches.
`intervalMin`	integer (int32)	yes	Minutes between scheduled runs, clamped to 5..=1440.
`label`	string \| null	no
`lastRunAt`	integer \| null (int64)	no	When the last run started, epoch milliseconds.
`lastScore`	integer \| null (int32)	no	The legacy compatibility score of the last run that produced a report.
`minimumScore`	integer \| null (int32)	no	Alert when the frozen compatibility score first falls below this floor. Optional so watches stored before absolute thresholds existed retain their exact delta-only behaviour.
`mode`	WatchMode	no
`scoreDropThreshold`	integer (int32)	yes	Alert when the score drops by at least this many points vs the last run.
`seoDropThreshold`	integer \| null (int32)	no	Alert when the technical SEO score drops by at least this many points vs the last run. Optional and defaulted so stored watches created before SEO scoring existed keep deserializing; absent means SEO regressions are not watched, exactly the pre-SEO behaviour. Separate from `score_drop_threshold` because the two scores measure different things (legacy compatibility vs technical search readiness) and a site can regress badly in one while the other is unchanged.
`trialId`	string \| null	no	Hashed entitlement identity, never the trial bearer capability.
`url`	string	yes	The audited URL, normalized and stripped of credentials.
`webhook`	string \| null	no	Where alerts are POSTed as JSON, stripped of credentials.

Used by: POST /audit/watches, GET /audit/watches/{id}, POST /audit/watches/{id}/run

Autocomplete

Autocomplete response. Equivalent to Kotlin `Autocomplete`.

Properties
Name	Type	Required	Description
`results`	array<string>	yes

Used by: GET /sites/{siteId}/autocomplete

AvailabilityResult

Result of a bulk `availability` generation.

Properties
Name	Type	Required	Description
`created`	integer (int32)	yes	Windows actually created.
`skipped`	integer (int32)	yes	Candidate windows skipped (overlapped an existing window, or hit the cap).

Used by: POST /assets/owners/{ownerId}/assets/{assetId}/availability

BookingCounts

Booking counts by (effective) lifecycle state for a [`OwnerReport`].

Properties
Name	Type	Required
`cancelled`	integer (int32)	yes
`completed`	integer (int32)	yes
`confirmed`	integer (int32)	yes
`expired`	integer (int32)	yes
`held`	integer (int32)	yes

BookingFieldDef

An owner-defined field a consumer fills in at booking time — e.g. a license plate, headcount, delivery address, or a `select` from a fixed option list. Definitions live on the [`Asset`]; the consumer-supplied values live on the [`Reservation`] (`fields`). Cross-vertical and self-contained.

Properties
Name	Type	Required	Description
`key`	string	yes	Stable machine key (`[A-Za-z0-9_-]`, unique per asset) — the key under which the consumer's value is stored in `Reservation.fields`.
`label`	string	yes	Human-facing label the booking UI renders.
`options`	array<string>	no	Allowed values for a `select` field (ignored for other types).
`required`	boolean	no	Whether the consumer must supply a non-empty value.
`type`	FieldType	no

BookingPolicy

A per-asset booking policy: how close to a slot's start a consumer may still book it, and how close they may still cancel it. `0` = no restriction; an all-zero policy is normalised to "no policy". Owner-initiated cancels always bypass the cancel cutoff.

Properties
Name	Type	Required	Description
`cancelCutoffMinutes`	integer (int32)	no	A consumer can't cancel a booking within this many minutes of the slot start.
`minNoticeMinutes`	integer (int32)	no	A consumer can't book/hold a window starting within this many minutes of now.

BrokenLink

One broken internal link found during the crawl.

Properties
Name	Type	Required	Description
`referencedBy`	string	yes	A page that referenced this link (the first one seen).
`status`	integer \| null (int32)	no	The HTTP status (4xx/5xx), or `None` when the link was unreachable.
`url`	string	yes

BulkDeleteResult

Result of a bulk window delete.

Properties
Name	Type	Required	Description
`deleted`	integer (int32)	yes

Used by: DELETE /assets/owners/{ownerId}/assets/{assetId}/windows

CdnChange

A report-level CDN / edge-network transition between two snapshots. This is an *origin* property (every same-origin probe sees the same CDN), so it lives beside `score_delta` rather than in the per-URL `changes` list.

Properties
Name	Type	Required	Description
`after`	string \| null	no	Vendor on the AFTER snapshot.
`before`	string \| null	no	Vendor on the BEFORE snapshot (absent when unnamed or not detected).
`kind`	string	yes	`added` (origin → now behind a CDN), `removed` (CDN no longer fingerprinted), or `changed` (different vendor, e.g. Fastly → Cloudflare).

CdnInfo

Whether — and which — CDN / edge network fronts the audited origin, inferred from response headers. Derived at fetch time and kept deliberately compact and *value-free*: the tell-tale headers (`cf-ray`, `x-amz-cf-id`, …) carry per-request-unique values, so we record only the header **names** that matched. That keeps the signal stable across re-audits (no spurious `header-changed` in the snapshot diff).

Properties
Name	Type	Required	Description
`detected`	boolean	no	True when a CDN/edge network was positively identified (a vendor signature matched, or the RFC 8586 `CDN-Loop` header was present).
`evidence`	array<string>	no	Stable evidence: the response-header names that triggered the match (values omitted — see the struct docs).
`vendor`	string \| null	no	The identified provider (e.g. `Cloudflare`, `Fastly`, `Amazon CloudFront`) when a vendor-specific signature matched; `None` when a CDN is present but the vendor could not be named.

ChainCert

One certificate in the chain the server presented (leaf and each additional cert), summarised for the report. A compact, SSL-Labs-style chain view.

Properties
Name	Type	Required	Description
`daysRemaining`	integer \| null (int64)	no
`issuer`	string \| null	no
`keyBits`	integer \| null (int32)	no
`keyType`	string \| null	no	`EC` / `RSA` / `Ed25519`.
`notAfter`	integer (int64)	no	`notAfter`, epoch seconds.
`notAfterUtc`	string \| null	no
`notBefore`	integer \| null (int64)	no	Additional evidence is optional so historical chain summaries stay unknown.
`notBeforeUtc`	string \| null	no
`selfIssued`	boolean \| null	no	Self-issued certificates are reported but excluded from renewal warnings.
`sha256`	string \| null	no
`signatureAlgorithm`	string \| null	no
`subject`	string \| null	no
`validNow`	boolean \| null	no

ClientSignals

Client-side runtime signals POSTed by the tag. Every field is optional: a *missing* field is "unknown" and is **not** penalised, only a field that is present-and-bot-like contributes to the score (so an empty `{}` beacon scores 0 on the client side and falls back to the server-side verdict).

Properties
Name	Type	Required	Description
`hardwareConcurrency`	number \| null (double)	no	`navigator.hardwareConcurrency` — 0 is a headless tell.
`languagesCount`	integer \| null (int32)	no	`navigator.languages.length` — headless contexts often report 0.
`pluginsCount`	integer \| null (int32)	no	`navigator.plugins.length` — 0 on a non-mobile UA is mildly suspect.
`referrer`	string \| null	no	`document.referrer` — the visit's traffic source. Reduced to its host and stored for the top-referrers rollup; never used for scoring.
`url`	string \| null	no	`location.href` of the tracked page — used only to drop same-site (internal-navigation) referrers from that rollup.
`webdriver`	boolean \| null	no	`navigator.webdriver` — true under automation (Selenium/Puppeteer/…).

Used by: POST /visit.json, POST /visit/enrich.json

CollectionPeriod

The dates the field data was collected over, `YYYY-MM-DD`.

Properties
Name	Type	Required	Description
`firstDate`	string	no
`lastDate`	string	no

CompressionEvidence

Result of repeating the page request with `Accept-Encoding: br, gzip`. Only the response headers are read; the body is discarded unread.

Properties
Name	Type	Required	Description
`contentEncoding`	string \| null	no	The response's `Content-Encoding`, absent when it sent none.
`errorKind`	string \| null	no	Transport failure kind when no response arrived; same vocabulary as `ProbeResult.errorKind`.
`evaluated`	boolean	no	A response arrived.
`requestedEncodings`	string	no	The `Accept-Encoding` value sent, `br, gzip`.
`status`	integer \| null (int32)	no
`varyAcceptEncoding`	boolean	no	The response's `Vary` names `Accept-Encoding`.

CountRow

One row of a "top N" breakdown — a path (top pages) or a referrer host (top referrers) with its visitor / view split over the window.

Properties
Name	Type	Required	Description
`bot`	integer (int64)	yes
`human`	integer (int64)	yes
`label`	string	yes	The path (top pages) or referrer host (top referrers).
`uniqueVisitors`	integer (int64)	yes	Distinct visitors (by client IP) — the sort key for the breakdown.
`visits`	integer (int64)	yes	Page views (total beacons) for this label.

CrawlCoverage

Honest accounting for the bounded discovery and link sample.

Properties
Name	Type	Required	Description
`homepageLinksDiscovered`	integer	no
`homepageLinksTruncated`	boolean	no
`incompletePages`	integer	no
`internalLinksChecked`	integer	no
`internalLinksDiscovered`	integer	no
`linkCheckLimitReached`	boolean	no
`pageLimitReached`	boolean	no
`pagesAudited`	integer	no
`pagesDiscovered`	integer	no
`pagesSelected`	integer	no
`pagesWithTruncatedLinks`	integer	no
`redirectBudgetExhausted`	boolean	no	At least one otherwise-safe same-host redirect was not followed because its additional request could not be admitted under the target budget.
`requestedLimit`	integer	no
`siteSearchTruncated`	boolean	no
`siteSearchUrlsDiscovered`	integer	no
`sitemapByteLimitReached`	boolean	no
`sitemapBytesRead`	integer	no	Raw response bytes retained across sitemap attempts, including error responses; this is resource accounting, not valid sitemap XML size.
`sitemapDocumentReferencesRejected`	integer	no	Invalid, out-of-scope, too-deep, or over-queue-limit document references rejected before admission. These are not discovered/skipped documents.
`sitemapDocumentsAttempted`	integer	no	Admitted document candidates for which an HTTP request was attempted.
`sitemapDocumentsByteLimited`	integer	no
`sitemapDocumentsDiscovered`	integer	no	Distinct normalized, in-scope sitemap document candidates admitted to the traversal queue, including the two conventional optional probes.
`sitemapDocumentsFailed`	integer	no	Transport failures and every non-2xx status except a 404 from an optional conventional probe. This can overlap `fetched` for HTTP failures.
`sitemapDocumentsFetched`	integer	no	Attempts that received an HTTP response, regardless of its status.
`sitemapDocumentsInvalid`	integer	no	Fully received responses whose XML/content is malformed or unsupported.
`sitemapDocumentsSkipped`	integer	no	Admitted document candidates left unattempted when a traversal cap was reached. Together with `attempted`, this partitions `discovered`.
`sitemapDocumentsStreamInterrupted`	integer	no
`sitemapDocumentsTruncated`	integer	no	Responses not read to EOF, partitioned by the next two counters.
`sitemapEntriesSeen`	integer	no
`sitemapEntryLimitReached`	boolean	no
`sitemapExists`	boolean	no
`sitemapFetchLimitReached`	boolean	no
`sitemapLastmodFuture`	integer	no
`sitemapLastmodInvalid`	integer	no
`sitemapQueueLimitReached`	boolean	no
`sitemapUrlsDuplicate`	integer	no
`sitemapUrlsInvalid`	integer	no
`sitemapUrlsOutOfScope`	integer	no
`sitemapUrlsValid`	integer	no

CrawlDiagnostic

Stable, sampled crawl-level diagnostic. Evidence is sorted, deduplicated, and capped so a link farm or malformed sitemap cannot inflate the report.

Properties
Name	Type	Required
`evidence`	array<string>	no
`id`	string	no
`message`	string	no
`sampled`	boolean	no
`severity`	string	no

CrawlDiagnostics

Why a crawl indexed the page count it did. Returned on [`CrawlerJobResult::diagnostics`]. Every counter is the number of URLs that ended in that outcome; `indexed` equals [`CrawlerJobResult::page_count`]. `summary` is a human-readable explanation, most useful when `indexed` is zero or every indexed page had no extractable text (a client-side-rendered site).

Properties
Name	Type	Required	Description
`depthFiltered`	integer (int64)	no	URLs excluded because they sit deeper than the crawl's max depth (link-distance from the seed). The depth cap is an internal crawl bound, so a large count means the site's structure is deeper than the crawler follows — same invisible-drop family as `scope_filtered`. Additive field; `#[serde(default)]` keeps pre-field payloads parseable.
`emptyBody`	integer (int64)	yes	Subset of `indexed` whose extracted body text was empty — the signal of a client-side-rendered (JavaScript SPA) page that will not produce useful search results.
`fetchError`	integer (int64)	yes	URLs that never produced a usable HTTP response (DNS, TLS, connection, timeout, or an empty/unreadable body).
`fetched`	integer (int64)	yes	URLs that reached a fetch attempt and produced a terminal outcome (everything below except `robotsBlocked` and `scopeFiltered`, which are excluded before any HTTP request is made).
`frontierDropped`	integer (int64)	no	Candidate URLs shed because the crawl frontier hit its internal bound (`FRONTIER_MAX`) — only plausible on extremely link-dense hosts. Sheds are candidates that were never evaluated, not pages that failed. Additive field; `#[serde(default)]` keeps pre-field payloads parseable.
`httpError`	integer (int64)	yes	Fetched URLs that returned a non-2xx HTTP status (often 403 bot protection or a 5xx).
`indexError`	integer (int64)	yes	Pages fetched successfully but rejected by the search backend on write — a server-side error, not a problem with the crawled site. `indexed` (and `pageCount`) already exclude these, so the response stays truthful about what the store actually holds.
`indexed`	integer (int64)	yes	Pages stored in the index. Equals `CrawlerJobResult.pageCount`.
`nonHtml`	integer (int64)	yes	2xx responses whose content-type was not indexable HTML/PDF.
`robotsBlocked`	integer (int64)	yes	URLs excluded before fetch because robots.txt disallows the crawler user-agent (`opty`).
`samples`	array<DiagnosticSample>	yes
`scopeFiltered`	integer (int64)	no	URLs excluded before fetch because they fall outside the crawl scope: the crawler only follows URLs under the SEED URL'S PATH PREFIX (`should_crawl_url`), plus extension/query filters. A large count next to a tiny `indexed` is the signature of a too-narrow seed — e.g. an article URL instead of the host root (build #2391, where this drop was invisible and cost a live bisect to find). `#[serde(default)]` keeps payloads from pre-field builds parseable.
`seedRedirectedTo`	string \| null	no	Set when the seed URL redirected and the crawl rebased its scope onto the redirect's final scheme/host/port (`engine::rebase_scope`) — the operator gave one URL and the crawl ran against another, which qualification needs to know. Additive field; `#[serde(default)]` keeps pre-field payloads parseable and `None` stays off the wire.
`summary`	string	yes

CrawlPage

One audited page in a crawl.

Properties
Name	Type	Required	Description
`class`	string	yes	`present` / `redirected` / `error` / `unreachable`.
`complete`	boolean	no	Whether the response body reached EOF without hitting the byte cap or a stream error. `false` for unreachable pages and legacy deserializations.
`contentType`	string \| null	no
`finalUrl`	string \| null	no
`linkCount`	integer	yes	Same-host links harvested from this page (for the link check).
`linksTruncated`	boolean	no	True when more same-host links existed than the per-page crawl cap.
`pageEncoding`	null \| PageEncodingProvenance	no
`provenance`	array<DiscoverySource>	no	Every bounded discovery source which named this URL.
`seo`	null \| SeoReport	no
`size`	integer \| null	no
`status`	integer \| null (int32)	no
`title`	string \| null	no
`url`	string	yes

CrawlReport

Full crawl report.

Properties
Name	Type	Required	Description
`brokenLinks`	array<BrokenLink>	no
`complete`	boolean	no	True when every operation in the selected bounded sample completed and no discovery/link resource limit was reached. This never means whole-web coverage; [`sampled`] remains true.
`coverage`	CrawlCoverage	no
`diagnostics`	array<CrawlDiagnostic>	no
`discoveredVia`	string	yes	How the page set was discovered: `sitemap` / `sitemap-index` / `homepage-links` / `site-search`.
`findings`	array<string>	no
`host`	string	yes
`pages`	array<CrawlPage>	yes
`pagesAudited`	integer	yes
`pagesDiscovered`	integer	yes	Distinct pages discovered before the `limit` cap.
`sampled`	boolean	no
`score`	integer (int32)	yes	Aggregate health: percent of audited pages returning a healthy 2xx/3xx.
`seo`	CrawlSeoSummary	no
`target`	string	yes
`unicodeHost`	string \| null	no	Unicode presentation form of an IDN host. `host` remains canonical ASCII/Punycode for network and security decisions.

Used by: GET /audit/crawl

CrawlSeoSummary

Mean SEO score over scoreable sampled pages, kept separate from the legacy crawl health score.

Properties
Name	Type	Required
`complete`	boolean	no
`meanScore`	integer \| null (int32)	no
`pagesComplete`	integer	no
`pagesScored`	integer	no
`pagesWithAnalysis`	integer	no
`scoreModelVersion`	integer \| null (int32)	no

CrawlStatus

Crawl status for a site. Equivalent to Kotlin `CrawlStatus`.

Properties
Name	Type	Required
`crawled`	string	yes
`pageCount`	integer (int64)	no
`siteId`	string \| null (uuid)	no
`siteProfile`	null \| SiteProfile	no

CrawlerJobResult

Result of a crawl job. Equivalent to Kotlin `CrawlerJobResult`.

Properties
Name	Type	Required
`diagnostics`	CrawlDiagnostics	no
`pageCount`	integer	yes
`urls`	array<string>	yes

Used by: POST /sites/{siteId}/crawl, POST /sites/{siteId}/recrawl

CurlResponse

Properties
Name	Type	Required	Description
`body`	string	yes	Response body content
`error`	null \| FetchError	no
`headers`	map<string, string>	yes	Lower-cased response headers. Repeated values are comma-joined.
`statusCode`	integer (int32)	yes	HTTP status code from the fetched URL
`url`	string	yes	The URL that was fetched

Used by: GET /curl.json

CwvAssessment

Whether the page or origin passes the Core Web Vitals assessment.

Type: string one of "passed", "failed", "insufficientData", "unknown"

DelegatedAsset

An asset returned to an operational Dispatcher. The root `ownerId` bearer is intentionally absent; operational configuration stays available.

Properties
Name	Type	Required
`bookingFields`	array<BookingFieldDef>	no
`createdAt`	integer (int64)	yes
`currency`	string	yes
`description`	string \| null	no
`id`	string	yes
`kind`	string	yes
`name`	string	yes
`policy`	null \| BookingPolicy	no
`promoCodes`	array<PromoCode>	no
`timezone`	string	yes

DelegatedAssetWithWindows

Properties
Name	Type	Required
`asset`	DelegatedAsset	yes
`windowCount`	integer (int32)	yes
`windows`	array<Window>	yes

DelegatedAuditEvent

A delegated audit row. Reservation/waitlist IDs are public mutation capabilities and detail is free-form, potentially credential-bearing text, so neither crosses this non-root boundary. Dispatchers get their booking capabilities from the operational asset/window/reservation surfaces.

Properties
Name	Type	Required
`action`	string	yes
`assetId`	string \| null	no
`at`	integer (int64)	yes
`windowId`	string \| null	no

DeliveryOutcome

Type: string one of "pending", "accepted", "queued", "failed", "cancelled"

DiagnosticSample

One concrete failing-URL example carried in [`CrawlDiagnostics::samples`]. A bounded list of examples so an operator sees *which* URLs failed and *why*, not just a count. `detail` carries the HTTP status text or content-type when the reason has one.

Properties
Name	Type	Required	Description
`detail`	string \| null	no
`reason`	string	yes	Reason tag, matching a `CrawlDiagnostics` counter: one of `httpError`, `nonHtml`, `fetchError`, `robotsBlocked`, `scopeFiltered`, `depthFiltered`, `indexError`. (Frontier sheds carry no samples — they are counted in bulk, never per URL.)
`url`	string	yes

DiscountKind

How a [`PromoCode`] reduces a window's per-unit cost.

Type: string one of "percent", "fixed"

DiscoverySource

How a URL entered the bounded crawl sample.

Type: string one of "target", "sitemap", "homepage-link", "site-search"

Echo

JSON payload for the echo endpoint. Mirrors the schema of `fsly::echo::Echo`, plus api-specific request-derived bot/fraud signals.

Properties
Name	Type	Required	Description
`data`	string	yes	Request body data (empty for GET requests)
`fingerprint`	string	yes	SHA-256 fingerprint derived from selected headers
`fraud`	number (float)	yes	Fraud score (0.0 = trusted, 1.0 = highly suspicious). Combines cheap header/UA/JA3-JA4 heuristics with the IP/TLS reputation feeds (datacenter, VPN, Spamhaus DROP, abuse.ch SSLBL JA3).
`headers`	map<string, array<string>>	yes	Request headers (sorted alphabetically)
`host`	string	yes	Host header value
`iCloudPrivateRelay`	boolean	yes	True if IP is in iCloud Private Relay range
`ip`	string	yes	Client IP address
`ja3`	string	yes	JA3 TLS fingerprint hash (if available from upstream proxy)
`method`	string	yes	HTTP method (GET, POST, PUT, DELETE, etc.)
`query`	map<string, array<string>>	yes	Parsed query parameters
`scheme`	string	yes	URL scheme (http or https)
`session`	string	yes	Session hash (fingerprint + IP + cookie)
`torExitNode`	boolean	yes	True if IP is a known Tor exit node
`uri`	string	yes	Request URI path
`version`	string	yes	HTTP version

Used by: GET /echo.json

EmailDelivery

Properties
Name	Type	Required
`alertAt`	integer (int64)	yes
`id`	string	yes
`kind`	string	yes
`state`	DeliveryOutcome	yes
`updatedAtMs`	integer (int64)	yes

EmailNotificationStatus

Properties
Name	Type	Required
`delivery`	null \| EmailDelivery	no
`email`	string \| null	no
`pending`	boolean	yes
`pendingEmail`	string \| null	no
`pendingExpiresAtMs`	integer \| null (int64)	no
`verified`	boolean	yes

Used by: GET /audit/watches/{id}/notifications/email, POST /audit/watches/{id}/notifications/email/verify

EncodingResponse

Response payload for `/encoding.json`. Field names are camelCase to match the `/...json` API conventions.

Properties
Name	Type	Required	Description
`base64Decoded`	string	yes	Base64-decoded input as text. Empty when the input is not valid Base64 or when it decodes to bytes that are not text in the applied charset — read `base64Valid` and `base64DecodedBytes` to tell those two cases apart.
`base64DecodedBytes`	integer	yes	Number of bytes the input decoded to; `0` when `base64Valid` is false. A non-zero count with an empty `base64Decoded` means the input is valid Base64 carrying binary data rather than text.
`base64Encoded`	string	yes	Base64-encoded representation of raw bytes, standard alphabet (RFC 4648 section 4), padded with `=`.
`base64UrlEncoded`	string	yes	Base64-encoded representation of raw bytes, URL- and filename-safe alphabet (RFC 4648 section 5: `-` and `_` for `+` and `/`) with padding omitted — the form JWT/JOSE (RFC 7515) mandates.
`base64Valid`	boolean	yes	Whether the input value parses as Base64 at all. The decoder accepts both the standard and the URL-safe alphabet and tolerates missing padding, so this is `true` for far more inputs than it looks — any four-character run of alphabet characters decodes to three bytes.
`binary`	string	yes	Raw bytes in base 2, eight digits per byte, space separated. Unsigned, unlike the signed `octal` / `decimal` / `hex` views above, because a negative binary byte is not a thing anyone means by "text to binary".
`byteLength`	integer	yes	Byte count of the raw input under the applied charset. Differs from `rawLength` for any non-ASCII input (`ä` is one character, two bytes).
`charset`	string	yes	Applied charset (may differ from requested if unsupported)
`decimal`	string	yes	Decimal representation of raw bytes
`hash`	integer (int64)	yes	FNV-1a 64-bit hash of the raw input. A non-cryptographic checksum for bucketing and change detection — deliberately named in the docs so callers can reproduce it, and deliberately not a substitute for the SHA-256 above.
`hex`	string	yes	Hexadecimal representation of raw bytes
`hexDecoded`	string	yes	The input read as hex and decoded back to text. Tolerates whitespace, a leading `0x`, and `:` or `-` separators. Empty when the input is not hex or does not decode to text — read `hexValid` and `hexDecodedBytes` to tell those apart, exactly as with Base64.
`hexDecodedBytes`	integer	yes	Number of bytes the input decoded to when read as hex; `0` when `hexValid` is false.
`hexEncoded`	string	yes	Raw bytes as one contiguous lowercase hex string. This is the form `xxd -p`, checksums and wire dumps use — distinct from the bracketed, signed, Kotlin-style `hex` field above.
`hexValid`	boolean	yes	Whether the input parses as hex. Requires an even number of hex digits after separators are removed.
`htmlDecoded`	string	yes	HTML character references in the input resolved back to text. Covers every numeric reference (`©`, `©`) plus the HTML 4.01 Latin-1, special and common symbol named entities. An unrecognised entity is left exactly as it stands rather than dropped, so decoding never silently loses text.
`htmlEncoded`	string	yes	HTML-escaped input: `&`, `<`, `>`, `"` and `'` become character references, so the value is safe to interpolate into element text or a quoted attribute. `'` uses the numeric `'` rather than `'`, which HTML 4 does not define.
`jsonEscaped`	string	yes	The input as a complete, quoted JSON string literal, ASCII-safe: every non-ASCII character is written as `\uXXXX` (surrogate pairs above U+FFFF). Paste-ready into JSON, JavaScript, Java or any other format that takes JSON string syntax — the surrounding quotes are included.
`jsonUnescaped`	string	yes	The input read as a JSON string literal, with `\n`, `\t`, `\uXXXX` and friends resolved. The surrounding quotes are optional. Empty when the input is not a well-formed JSON string; see `jsonValid`.
`jsonValid`	boolean	yes	Whether the input parses as a JSON string literal.
`md5`	string	yes	MD5 hash as lowercase hex
`octal`	string	yes	Octal representation of raw bytes
`raw`	string	yes	Original input value
`rawLength`	integer	yes	Character count of raw input (Unicode scalar values, not UTF-16 units)
`sha1`	string	yes	SHA-1 hash as lowercase hex
`sha256`	string	yes	SHA-256 hash as lowercase hex
`urlDecoded`	string	yes	URL/percent-decoded input
`urlEncoded`	string	yes	URL/percent-encoded representation

Used by: GET /encoding.json

EngagementAggregate

Aggregate engagement depth over a window of visits — returned as `VisitStats.engagement` and rendered on the dashboard as a KPI row. Answers *"how sticky was this site?"* with three ROBUST numbers (medians rather than means, so a couple of tab-open-for-hours outliers don't skew) plus one marketing KPI (`engaged_rate_pct`).

Properties
Name	Type	Required	Description
`engagedRatePct`	number \| null (double)	no	Marketing KPI — share of samples that count as "engaged": time on page ≥ 10 s, OR scroll depth ≥ 50 %, OR at least one interaction. In percent (0..=100).
`p50Interactions`	integer \| null (int32)	no	Median interaction count per visit (0..3 for the three counters: click, keydown, pointerdown).
`p50ScrollPct`	number \| null (double)	no	Median deepest scroll depth reached, as a percentage of document height (0..=100).
`p50TimeOnPageMs`	integer \| null (int64)	no	Median visible time on page (ms) across all samples in the window. Client-side already capped at 30 min, so no outlier truncation here.
`p75TimeOnPageMs`	integer \| null (int64)	no	P75 visible time on page (ms) — surfaces the tail (how long the stickiest quartile actually stayed).
`samples`	integer (int64)	yes	Total number of visits in the window that contributed at least one engagement field. When zero, all fields are `None`.

EntropyResponse

Mirrors the Kotlin `Entropy` DTO shape, but served as `/entropy.json`. Kotlin source (for reference): - uuid: UUID.randomUUID() - secureRandomLong: Random().nextLong() - secureRandomFloat: Random().nextFloat() - secureRandomGaussian: Random().nextGaussian() - secureRandomInt: Random().nextInt() - timestamp: Instant.now() Rust note: - We intentionally do *not* use "secure" entropy sources; we stick to a fast RNG suitable for non-cryptographic "jitter" / uniqueness. - Timestamp is ISO 8601 (RFC 3339) in UTC, which is the natural JSON representation in Rust. (Kotlin/Java `Instant` also serializes as an ISO timestamp under typical Jackson configs.)

Properties
Name	Type	Required	Description
`secure_random_float`	number (float)	yes	Random float in range [0.0, 1.0)
`secure_random_gaussian`	number (double)	yes	Random Gaussian-distributed double (mean=0, stddev=1)
`secure_random_int`	integer (int32)	yes	Random 32-bit signed integer
`secure_random_long`	integer (int64)	yes	Random 64-bit signed integer
`timestamp`	string	yes	Current timestamp as epoch milliseconds
`uuid`	string	yes	Random UUID v4

Used by: GET /entropy.json

FetchError

Structured MCP fetch failure. HTTP responses, including 4xx/5xx, are not failures and remain [`CurlResponse`] values. This type is reserved for validation, SSRF, transport, and bounded-body failures.

Properties
Name	Type	Required
`code`	string	yes
`kind`	FetchErrorKind	yes
`message`	string	yes
`retryAfter`	string \| null	no
`status`	integer \| null (int32)	no

FetchErrorKind

JSON response payload (mirrors Kotlin `Curl`).

Type: string one of "invalid_request", "ssrf", "dns", "tls", "timeout", "rate_limited", "body_cap", "upstream", "transport"

FetchedPage

Response DTO for fetched/indexed pages. Matches the Kotlin `FetchedPage` structure.

Properties
Name	Type	Required
`body`	string \| null	no
`id`	string \| null	no
`labels`	array<string>	no
`siteId`	string \| null (uuid)	no
`thumbnail`	string \| null	no
`title`	string \| null	no
`updated`	string \| null	no
`url`	string \| null	no

Used by: GET /pages/{id}, GET /sites/{siteId}/pages, PUT /sites/{siteId}/pages, PUT /sites/{siteId}/pages/{pageId}

FieldData

Where real-user field data comes from and what it says. The only source is Google's Chrome UX Report: public, aggregated 75th-percentile data from real Chrome visits. Without a configured API key the state is `notConfigured` and nothing else is set.

Properties
Name	Type	Required	Description
`collectionPeriod`	null \| CollectionPeriod	no
`coreWebVitals`	null \| CwvAssessment	no
`formFactor`	string	no	`all`: every device type combined.
`key`	string \| null	no	The URL or origin the record is for.
`metrics`	array<FieldMetric>	no
`scope`	null \| FieldDataScope	no
`source`	string	no	`chromeUxReport`.
`state`	FieldDataState	no
`unavailableReason`	string \| null	no	Why the data is `unavailable`, for example `timeout`.

FieldDataScope

Type: string one of "url", "origin", "unknown"

FieldDataState

Type: string one of "notConfigured", "insufficientData", "complete", "unavailable"

FieldMetric

One real-user metric at the 75th percentile. The engine always sets `p75` and both thresholds; they are optional so that a stored report stays readable when a number is missing or `null`, which is how JSON carries a non-finite one.

Properties
Name	Type	Required	Description
`coreWebVital`	boolean	no	LCP, INP, and CLS are Core Web Vitals; FCP and TTFB are diagnostics.
`cruxMetric`	string	no	The Chrome UX Report metric name.
`distribution`	null \| RatingDistribution	no
`goodThreshold`	number \| null (double)	no
`id`	string	no	`lcp`, `inp`, `cls`, `fcp`, or `ttfb`.
`p75`	number \| null (double)	no
`poorThreshold`	number \| null (double)	no
`rating`	MetricRating	no
`unit`	string	no	`millisecond` or `unitless`.

FieldType

The value shape of an owner-defined [`BookingFieldDef`]. `Select` constrains the value to one of the field's `options`; the rest are free-form text / numeric / boolean values validated on booking.

Type: string one of "text", "number", "bool", "select"

FindingDetail

A finding plus everything a reader needs to act on it.

Properties
Name	Type	Required	Description
`category`	string	no	Report section this belongs to.
`docs`	string \| null	no	Primary specification or reference, when one exists.
`how`	string	no	How to address it.
`id`	string	no	Stable catalogue id, e.g. `header.csp.missing`. Safe to match on.
`message`	string	no	The same sentence that appears in `findings`.
`severity`	string	no	Advisory triage — independent of the frozen 0–100 score.
`title`	string	no	Short label for the finding kind.
`what`	string	no	What the thing being reported actually is.
`why`	string	no	Why it matters — the concrete consequence, not a platitude.

FoundPage

Found page in search results. Equivalent to Kotlin `FoundPage`.

Properties
Name	Type	Required
`body`	string \| null	no
`labels`	array<string>	no
`thumbnail`	string \| null	no
`title`	string \| null	no
`urlRaw`	string \| null	no

HarExportQuery

Query parameters for the HAR export endpoint. All parameters are optional. When none are provided, returns all HAR entries (up to the default limit).

Properties
Name	Type	Required	Description
`before`	string \| null	no	ISO 8601 datetime: only include entries crawled before this time
`contentType`	string \| null	no	Filter by MIME type (e.g. "text/html")
`limit`	integer \| null	no	Maximum entries to return (default: 100, max: 10000)
`maxTime`	number \| null (double)	no	Maximum response time in milliseconds
`minTime`	number \| null (double)	no	Minimum response time in milliseconds
`offset`	integer \| null	no	Number of entries to skip (default: 0)
`since`	string \| null	no	ISO 8601 datetime: only include entries crawled at or after this time
`sort`	string \| null	no	Sort field: "time", "status", "crawledAt" (default); prefix with "-" for descending
`status`	integer \| null (int32)	no	Filter by HTTP status code (e.g. 200, 404)
`url`	string \| null	no	URL prefix match (e.g. "https://example.com/blog")

HealthCheck

One stable weighted health check. `weight` is the model's nominal weight; only pass/fail checks contribute to `evaluatedWeight`.

Properties
Name	Type	Required
`id`	string	no
`reason`	string	no
`status`	HealthCheckStatus	no
`weight`	integer (int32)	no

HealthCheckStatus

Type: string one of "pass", "fail", "notApplicable", "unknown"

HealthEvaluationState

Type: string one of "complete", "partial", "notEvaluated"

HealthReport

Versioned successor to the frozen top-level health score.

Properties
Name	Type	Required
`checks`	array<HealthCheck>	no
`evaluatedWeight`	integer (int32)	no
`evaluationReasons`	array<string>	no
`evaluationState`	HealthEvaluationState	no
`score`	integer \| null (int32)	no
`scoreModelVersion`	integer (int32)	no

HtmlSpeedMetrics

Speed signals counted in the page's source HTML.

Properties
Name	Type	Required	Description
`crossOriginScriptHosts`	array<string>	no	Hosts other than the page's that serve its external scripts, sorted, at most 20.
`dnsPrefetchHints`	integer	no
`domElements`	integer	no	Elements inside `<body>`.
`firstImageLazy`	boolean	no	The first `<img>` in source order has `loading=lazy`.
`headStylesheets`	integer	no	Stylesheets in `<head>` for all media or screen. Browsers wait for these before the first render, so they are counted, not flagged.
`images`	integer	no	`<img>` elements.
`imagesWithoutDimensions`	integer	no	Images lacking a `width` or a `height` attribute.
`lazyImages`	integer	no	Images with `loading=lazy`.
`preconnectHints`	integer	no
`preloadHints`	integer	no
`preloadWithoutAs`	integer	no	Preload hints without an `as` attribute.
`renderBlockingScripts`	integer	no	External classic scripts in `<head>` without `async` or `defer`.

ImportResult

Counts of what an `import` wrote.

Properties
Name	Type	Required
`assets`	integer (int32)	yes
`members`	integer (int32)	yes
`reservations`	integer (int32)	yes
`webhooks`	integer (int32)	yes
`windows`	integer (int32)	yes

Used by: POST /assets/owners/{ownerId}/import

Inspection

Response payload for `/inspect.json`.

Properties
Name	Type	Required	Description
`echo`	Echo	yes
`whois`	Whois	yes

Used by: GET /inspect.json

LabTiming

Wall-clock timing of the page request, measured from after the audit's concurrency permits were granted, so queueing behind other probes is not included. Connection setup, TLS, and any followed redirects are.

Properties
Name	Type	Required	Description
`bodyComplete`	boolean	no	False when the body was truncated at the audit's cap or interrupted, so `totalMs` covers only the captured prefix.
`responseHeadersMs`	integer (int32)	no	Milliseconds until the final response's headers arrived.
`totalMs`	integer (int32)	no	Milliseconds until the (capped) body was read.

Member

A role-scoped delegated credential for an owner's team. `id` is the member's bearer token — it is used *in place of the ownerId* in the manager URL and is also the revoke handle. Additive to the single-bearer model: the root ownerId keeps working and is the only credential that can mint/revoke members.

Properties
Name	Type	Required
`createdAt`	integer (int64)	yes
`id`	string	yes
`label`	string	yes
`role`	Role	yes

Used by: GET /assets/owners/{ownerId}/members, POST /assets/owners/{ownerId}/members

MetricRating

Type: string one of "good", "needsImprovement", "poor", "unrated"

ModifyReservation

JSON body to modify an existing active booking in place — change the seat `quantity`, replace the custom `fields`, and/or edit the `note`. Every field is optional (omit to leave unchanged; a `note` of `""` clears it). A quantity increase is capacity-checked (may 409 `slot_full`); a decrease frees seats and may auto-promote a waitlister. Cost/currency/promo stay as booked.

Properties
Name	Type	Required
`fields`	map<string, string>	no
`note`	string \| null	no
`quantity`	integer \| null (int32)	no

Used by: PATCH /assets/owners/{ownerId}/reservations/{reservationId}/modify, PATCH /assets/reservations/{reservationId}/modify

NewAsset

JSON body to create an asset (the server mints `id`/`ownerId`/`createdAt`).

Properties
Name	Type	Required	Description
`bookingFields`	array<BookingFieldDef>	no	Owner-defined fields a consumer fills at booking (empty = none).
`currency`	string	no
`description`	string \| null	no
`kind`	string	no
`name`	string	yes
`policy`	null \| BookingPolicy	no
`promoCodes`	array<PromoCode>	no	Owner-defined discount codes (empty = none).
`timezone`	string	no	IANA timezone the slots are read in (default `UTC`).

Used by: POST /assets/owners/{ownerId}/assets

NewAvailability

JSON body to bulk-generate a recurring grid of windows. Timezone-free: all times are absolute epoch-ms. Example — eight 1-hour slots each day for a week: `{firstStart, slotMinutes:60, slots:8, repeatEveryMinutes:1440, repeatCount:7, cost, capacity}`.

Properties
Name	Type	Required	Description
`capacity`	integer (int32)	no
`cost`	number (double)	yes
`firstStart`	integer (int64)	yes	Epoch-ms start of the first slot.
`repeatCount`	integer (int32)	no	Number of repetitions (0/1 = the block once).
`repeatEveryMinutes`	integer (int32)	no	Offset between repetitions, minutes (0 = no repetition — a single block).
`slotMinutes`	integer (int32)	yes	Length of each slot, minutes.
`slots`	integer (int32)	yes	Number of back-to-back slots per repetition.

Used by: POST /assets/owners/{ownerId}/assets/{assetId}/availability

NewHold

JSON body to place a **tentative hold** on a seat. Like [`NewReservation`] but the booking auto-releases after `ttlSeconds` unless promoted with `confirm`.

Properties
Name	Type	Required	Description
`consumer`	string	yes
`fields`	map<string, string>	no	Values for the asset's custom booking fields, keyed by field `key`.
`note`	string \| null	no
`promoCode`	string \| null	no	Optional discount code (case-insensitive).
`quantity`	integer (int32)	no	Units/seats to hold in this one call (default 1).
`ttlSeconds`	integer (int64)	yes	Seconds the hold lives before it auto-releases the seat (`HOLD_TTL_MIN_SECS`..=`HOLD_TTL_MAX_SECS`).

Used by: POST /assets/asset/{assetId}/windows/{windowId}/hold

NewMember

JSON body to mint a member token (server mints `id`/`createdAt`).

Properties
Name	Type	Required	Description
`label`	string	no	Optional human label (defaults to the role name).
`role`	string	yes	`dispatcher` (read + book + schedule) or `viewer` (read-only).

Used by: POST /assets/owners/{ownerId}/members

NewReservation

JSON body a consumer POSTs to book a window.

Properties
Name	Type	Required	Description
`consumer`	string	yes
`fields`	map<string, string>	no	Values for the asset's custom booking fields, keyed by field `key`.
`note`	string \| null	no
`promoCode`	string \| null	no	Optional discount code (case-insensitive); applies the asset's matching [`PromoCode`] to the snapshotted per-unit cost.
`quantity`	integer (int32)	no	Units/seats to reserve in this one call (default 1; must fit the window's remaining capacity and not exceed its total capacity).

Used by: POST /assets/asset/{assetId}/windows/{windowId}/reserve

NewWaitlist

JSON body to join a window's waitlist.

Properties
Name	Type	Required	Description
`consumer`	string	yes
`fields`	map<string, string>	no	Custom booking-field values to carry onto the promoted hold.
`note`	string \| null	no
`quantity`	integer (int32)	no	Seats wanted (default 1; must not exceed the window's total capacity).

Used by: POST /assets/asset/{assetId}/windows/{windowId}/waitlist

NewWebhook

JSON body to register a webhook (server mints `id`/`createdAt`, sanitizes `url`).

Properties
Name	Type	Required	Description
`events`	array<string>	no	Empty ⇒ subscribe to everything (`["*"]`).
`url`	string	yes

Used by: POST /assets/owners/{ownerId}/webhooks

NewWindow

JSON body to add a single utilization window (server mints `id`).

Properties
Name	Type	Required	Description
`capacity`	integer (int32)	no	How many can book this slot; defaults to 1.
`cost`	number (double)	yes
`end`	integer (int64)	yes
`start`	integer (int64)	yes

Used by: POST /assets/owners/{ownerId}/assets/{assetId}/windows

OutboundAggregate

Aggregate outbound clicks & downloads over a window of visits — returned as `VisitStats.outbound` and rendered on the dashboard as two side-by-side TOP-N panels. Answers *"which off-site destinations do my visitors care about, and what are they downloading?"* with counted-frequency tables. Rows are per-*event* (not per-visit): a single visit that clicked three outbound links contributes three to `total_outbound_clicks` and can appear three times in `top_hosts`.

Properties
Name	Type	Required	Description
`samples`	integer (int64)	yes	Total number of visits in the window that opted into `?outbound=true` (whether or not they actually clicked anything).
`topDownloads`	array<OutboundCountRow>	yes	Top download file extensions by event count (descending), capped at [`TOP_N`]. Empty when no outbound event carried a download extension.
`topHosts`	array<OutboundCountRow>	yes	Top external destination hosts by event count (descending), capped at [`TOP_N`]. Empty when no outbound event carried a host.
`totalDownloads`	integer (int64)	yes	Total download events (i.e. events with a `downloadExt` set) in the window. Same double-counting note as `total_outbound_clicks`.
`totalOutboundClicks`	integer (int64)	yes	Total outbound-click events (i.e. events with a `host` set) in the window. A download from an external host contributes to both this total and `total_downloads`.

OutboundCountRow

One row of a TOP-N outbound breakdown: a label (external destination host, or a lowercased download file extension) with the count of matching events in the window. Simpler than [`CountRow`] because the outbound aggregation is per-event (not per-visit), so unique-visitor and human/bot splits don't apply — an outbound click is either recorded or not.

Properties
Name	Type	Required	Description
`count`	integer (int64)	yes	Count of matching events in the window.
`label`	string	yes	External destination host (e.g. `github.com`) or download file extension (e.g. `pdf`), lowercased.

OutboundEvent

One outbound-click sample: an anchor click that pointed to another host (`host` set), or downloaded a known file type (`download_ext` set), or both. Emitted zero-or-more times per visit; batched into [`PageOutbound::events`] and beaconed at visit end. Never contains the raw href — only the destination host (used for TOP-N-hosts breakdowns) and/or the lowercased file extension (used for TOP-N-downloads breakdowns). URL paths, query strings, and fragments are dropped in the browser before the beacon.

Properties
Name	Type	Required	Description
`downloadExt`	string \| null	no	The download file extension (lowercased, no dot; e.g. `pdf`) when the href path ends with a known download extension; `None` for a bare external-navigation click.
`host`	string \| null	no	The destination host (e.g. `github.com`) when the click leaves the current site; `None` for same-host downloads. Lowercased.

OwnerExport

A complete, portable snapshot of an owner's data — assets (with their windows and bookings), members, and webhooks. The operator owns this: back it up, or re-`import` it into a fresh owner on another self-hosted instance (ids are preserved, so share links and booking receipts keep working). Audit log and waitlist queues (transient) are intentionally excluded.

Properties
Name	Type	Required
`assets`	array<AssetWithWindows>	no
`exportedAt`	integer (int64)	yes
`members`	array<Member>	no
`ownerId`	string	yes
`version`	integer (int32)	yes
`webhooks`	array<Webhook>	no

Used by: GET /assets/owners/{ownerId}/export, POST /assets/owners/{ownerId}/import

OwnerReport

An owner utilization + revenue report — pure aggregation over the owner's assets/windows/reservations (no new storage). Snapshot at `generatedAt`.

Properties
Name	Type	Required	Description
`assets`	integer (int32)	yes	Number of assets the owner publishes.
`bookings`	BookingCounts	yes
`generatedAt`	integer (int64)	yes	Epoch-ms the report was computed.
`past`	integer (int32)	yes	Active bookings whose window has already ended.
`revenueByCurrency`	map<string, number (double)>	yes	Realized/committed revenue (confirmed + completed) per currency; tentative holds are excluded.
`seatsBooked`	integer (int64)	yes	Seats consumed by active (non-cancelled, non-expired) bookings.
`seatsTotal`	integer (int64)	yes	Sum of window capacities (total bookable seats).
`upcoming`	integer (int32)	yes	Active bookings whose window starts in the future.
`utilizationPct`	number (double)	yes	`seatsBooked / seatsTotal * 100`, or `0` when there are no seats.
`windows`	integer (int32)	yes	Number of utilization windows across all assets.

Used by: GET /assets/owners/{ownerId}/report

PageEncodingProvenance

Character-decoding evidence for a fetched HTML page. Raw byte size and hash remain byte-based; this only describes the decoded view used by analyzers.

Properties
Name	Type	Required	Description
`encoding`	string	no	Canonical WHATWG encoding name, for example `UTF-8` or `windows-1251`.
`hadErrors`	boolean	no	Whether malformed byte sequences required replacement characters.
`source`	string	no	`bom`, `httpHeader`, `htmlMeta`, `xmlDeclaration`, or `fallback`.

PageEngagement

Engagement-depth sample for one visit, opt-in via `/analytics.js?engagement=true`. A cheap "how sticky was this pageview" complement to Core Web Vitals — the three fields answer *were they still there, how far did they read, did they touch anything?* No DOM contents, no URLs, no ids; only structural counters that describe the visit's shape. All fields optional so partial reports (tab closed pre-interaction, JS scroll disabled, etc.) still record.

Properties
Name	Type	Required	Description
`interactions`	integer \| null (int32)	no	Count of primary interactions during the visit: `click`, `keydown` (excluding modifier-only), and `pointerdown`. Deduped per-event-type so keyboard-repeat doesn't inflate the number.
`scrollPct`	number \| null (double)	no	Deepest scroll reached during the visit, as a percentage of document height (0..=100). `scrollY + innerHeight` over `scrollHeight`, ratcheted upward — never decreases on scroll-back.
`timeOnPageMs`	integer \| null (int64)	no	Wall-clock time the tab was foregrounded, ms — sum of visible spans between `visibilitychange`s. Capped at 30 min client-side to bound the aggregation tail (a tab left open overnight is not engagement).

Used by: POST /visit/engagement.json

PageMeta

SEO / correctness facts extracted from the page's HTML `<head>` + body. Presence-and-shape only — no scoring here; the report folds the notable gaps into `findings`.

Properties
Name	Type	Required	Description
`canonical`	string \| null	no	`<link rel=canonical>` href.
`charsetDeclared`	boolean	no	The document declares its character encoding in the markup: a `<meta charset>` or a `<meta http-equiv=content-type>` whose content carries `charset=`. Pages relying on the Content-Type header alone are still fine — [`quality_findings`] only flags the case where neither declares one.
`description`	string \| null	no	`<meta name=description>` content.
`h1Count`	integer	no	Count of `<h1>` elements (0 or >1 are both SEO smells).
`jsonLd`	boolean	no	At least one `<script type=application/ld+json>` structured-data block.
`lang`	string \| null	no	`<html lang>` value.
`mixedContent`	array<string>	no	`http://` sub-resource URLs referenced from an `https://` page — active mixed content the browser will block or downgrade the padlock over. Capped to a handful for report compactness.
`ogImage`	boolean	no	Open Graph image (`og:image`) present.
`ogTitle`	boolean	no	Open Graph title (`og:title`) present.
`robots`	string \| null	no	`<meta name=robots>` content (e.g. `noindex,nofollow`).
`title`	string \| null	no
`titleAssertable`	boolean	no	An exported Hurl suite may assert `title`: hurl, which decodes the whole body with the charset the Content-Type declares (UTF-8 when it declares none) and parses it with libxml2, and zforce, which reads the body as UTF-8, both read exactly this text through `normalize-space(//head/title)`. False when either would read another text - a no-break or ideographic space, a character reference they decode differently, a second or commented-out `<title>`, a body in another charset - and in reports captured before it was recorded.
`viewport`	boolean	no	A responsive `<meta name=viewport>` is present.

PageOutbound

Outbound-click / download batch for one visit, opt-in via `/analytics.js?outbound=true`. Beaconed once at `visibilitychange -> hidden` / `pagehide` (same pattern as vitals and engagement) so a single flush captures the whole visit. `events` may be empty — the collector still beacons at least once so the aggregation counts the visit as "opted in but had zero outbound events", distinguishing it from a site that never opted in at all.

Properties
Name	Type	Required	Description
`events`	array<OutboundEvent>	no	Zero-or-more outbound events accumulated during the visit.

Used by: POST /visit/outbound.json

PageVitals

Core Web Vitals sample for one visit, opt-in via `/analytics.js?vitals=true`. The four fields are Google's field-metric quartet (LCP + INP + CLS + TTFB); all are optional because a visit may report a partial set — e.g. the tab is closed before INP fires, or the page has zero interactions. Absent values are simply dropped from the aggregate; no imputation. Numeric ranges follow Google's own definitions: LCP / INP / TTFB in milliseconds; CLS unitless. Only structural / performance data; **no** DOM contents, no URLs, no ids.

Properties
Name	Type	Required	Description
`cls`	number \| null (double)	no	Cumulative Layout Shift (unitless, typically 0..1).
`inpMs`	number \| null (double)	no	Interaction to Next Paint (ms) — worst input-response latency in the session. Absent on visits with zero real interactions.
`lcpMs`	number \| null (double)	no	Largest Contentful Paint (ms) — main-content load time.
`ttfbMs`	number \| null (double)	no	Time to First Byte (ms) — network + server first-byte time from `performance.getEntriesByType('navigation')[0].responseStart`.

Used by: POST /visit/vitals.json

PerformanceReport

Advisory speed section of a one-page report. Never scored, never diffed.

Properties
Name	Type	Required	Description
`checks`	array<SeoCheck>	no	Advisory checks, category `performance`. None is weighted, `Fail`, or `High`, and none reaches `seo.checks`, the SEO score, or JUnit.
`fieldData`	FieldData	no
`html`	null \| HtmlSpeedMetrics	no
`labTiming`	null \| LabTiming	no
`modelVersion`	integer (int32)	no	[`PERFORMANCE_MODEL_VERSION`] of the rules that produced this section.
`transport`	TransportEvidence	no

ProbeResult

One probed URL's result.

Properties
Name	Type	Required	Description
`class`	string	no	Classification: `present` / `missing` (404) / `redirected` (3xx) / `soft-404` (200 + HTML where a non-HTML well-known file is expected) / `stale` (a 2xx security.txt past its RFC 9116 `Expires` timestamp) / `error` (4xx–5xx) / `unreachable` (no response).
`contentType`	string \| null	no
`error`	string \| null	no	Set instead of a status when the probe could not complete.
`errorKind`	string \| null	no	Stable, additive classification for a transport failure. When no response arrived, the legacy `error: "fetch_error"` value remains unchanged for compatibility. A failure after response headers instead retains the status, sets `truncated`, and records its kind here.
`finalUrl`	string \| null	no	The URL the probe actually landed on, set only when the client followed one or more redirects and the final URL differs from the requested one. Surfaces the redirect chain's endpoint (e.g. an `http→https` upgrade or a `www` canonicalisation) that a status-only view hides once the hops are auto-followed.
`headers`	map<string, string>	no	Curated response headers (lower-cased keys; see [`REPORTED_HEADERS`]).
`ok`	boolean	no	True when a response arrived with a 2xx/3xx status.
`path`	string	no	Logical label: `(page)` for the target, else the well-known path.
`sha256`	string \| null	no
`size`	integer \| null	no
`status`	integer \| null (int32)	no
`truncated`	boolean	no	True if the body hit [`MAX_PROBE_BYTES`] or its stream was interrupted; in either case the reported hash and size cover only the captured prefix.
`url`	string	no	The absolute URL probed.

PromoCode

An owner-defined discount code a consumer supplies at booking. Unlimited-use within an optional validity window; the discounted per-unit price is snapshotted onto the [`Reservation`] (`cost`) and the code recorded (`appliedCode`). (Per-code usage caps are a deferred additive extension.)

Properties
Name	Type	Required	Description
`amount`	number (double)	yes	Percentage (`0..=100`) for `percent`, or a flat amount for `fixed`.
`code`	string	yes	Case-insensitive code the consumer types (stored upper-cased).
`kind`	DiscountKind	no
`validFrom`	integer \| null (int64)	no	Optional epoch-ms lower bound the code becomes valid (inclusive).
`validUntil`	integer \| null (int64)	no	Optional epoch-ms upper bound the code stays valid (exclusive).

PublicWindow

A window as seen by a *consumer*: availability only — never a booker's details.

Properties
Name	Type	Required	Description
`capacity`	integer (int32)	yes
`cost`	number (double)	yes
`end`	integer (int64)	yes
`id`	string	yes
`remaining`	integer (int32)	yes
`reserved`	boolean	yes	Convenience flag: `remaining == 0`.
`start`	integer (int64)	yes
`waitlisted`	integer (int32)	yes	How many consumers are queued on this window's waitlist.

RatingDistribution

Share of page loads in each rating band, 0.0 to 1.0. Each share is optional so that a stored report stays readable when one is missing or `null`.

Properties
Name	Type	Required
`good`	number \| null (double)	no
`needsImprovement`	number \| null (double)	no
`poor`	number \| null (double)	no

RescheduleRequest

JSON body to reschedule a booking onto a different window of the same asset.

Properties
Name	Type	Required	Description
`windowId`	string	yes

Used by: POST /assets/reservations/{reservationId}/reschedule

Reservation

A consumer's booking of a window. `id` doubles as the booker's capability to cancel/reschedule it. Snapshots cost + currency at booking time.

Properties
Name	Type	Required	Description
`appliedCode`	string \| null	no	The promo code applied to this booking, if any (upper-cased).
`assetId`	string	yes
`consumer`	string	yes	Who booked — a free-form name or email the consumer supplies.
`cost`	number (double)	yes	Per-unit price snapshotted at booking time — already discounted if an `appliedCode` promo was used. Booking total = `cost * quantity`.
`currency`	string	yes
`fields`	map<string, string>	no	Consumer-supplied values for the asset's [`BookingFieldDef`]s (empty = none).
`holdExpiresAt`	integer \| null (int64)	no	When a `Held` booking auto-releases (epoch-ms UTC). Set only while the reservation is a live hold; cleared once confirmed.
`id`	string	yes	Booking receipt id (UUID) — also the consumer's cancel/reschedule capability.
`note`	string \| null	no
`quantity`	integer (int32)	no	How many capacity units this booking consumes (group/quantity booking). Defaults to 1; `cost` is the per-unit window cost (total = `cost * quantity`).
`reservedAt`	integer (int64)	yes
`status`	ReservationStatus	no
`windowId`	string	yes

Used by: POST /assets/asset/{assetId}/windows/{windowId}/hold, POST /assets/asset/{assetId}/windows/{windowId}/reserve, POST /assets/owners/{ownerId}/reservations/{reservationId}/cancel, PATCH /assets/owners/{ownerId}/reservations/{reservationId}/modify, POST /assets/reservations/{reservationId}/cancel, POST /assets/reservations/{reservationId}/confirm, PATCH /assets/reservations/{reservationId}/modify, POST /assets/reservations/{reservationId}/reschedule

ReservationRow

One row of the manager's booking list — a reservation with asset/window context.

Properties
Name	Type	Required
`assetId`	string	yes
`assetName`	string	yes
`end`	integer (int64)	yes
`reservation`	Reservation	yes
`start`	integer (int64)	yes
`windowId`	string	yes

ReservationRowsResponse

Role-dependent serialization for the manager reservation list.

Type: array<ReservationRow> | array<ViewerReservationRow>

Used by: GET /assets/owners/{ownerId}/reservations

ReservationStatus

The lifecycle state of a booking. `Confirmed`, `Completed` and (an unexpired) `Held` consume capacity; `Cancelled` and `Expired` free it. `Held` is a *tentative* reservation minted by [`AssetStore::hold`] that auto-releases at its `holdExpiresAt` — promoted to `Confirmed` by [`AssetStore::confirm`], or swept to `Expired` when its deadline passes. (Delivery-specific states — dispatched/delivered/failed — are a planned additive extension of this enum.)

Type: string one of "confirmed", "cancelled", "completed", "held", "expired"

Role

The effective authority a manager-surface caller holds. The root `ownerId` resolves to [`Role::Owner`] (full control); a minted member token resolves to its scoped role. Only `Dispatcher`/`Viewer` are mintable as members.

Type: string one of "owner", "dispatcher", "viewer"

SearchResult

Search result DTO. Equivalent to Kotlin `Result`.

Properties
Name	Type	Required	Description
`query`	string	yes
`results`	array<FoundPage>	yes

Used by: GET /sites/{siteId}/search

SecurityAnalysis

Beyond mere presence: the *quality* of a page's security headers. A header can be present yet toothless (a `Content-Security-Policy` allowing `unsafe-inline`, an `HSTS` with a one-second `max-age`), which a presence-only check scores identically to a strong one. This captures the distinctions that matter and rolls them into a letter [`grade`].

Properties
Name	Type	Required	Description
`csp`	boolean	no	`Content-Security-Policy` present at all.
`cspStyleUnsafeInline`	boolean	no	The effective STYLE policy (`style-src`, else `default-src`) permits `unsafe-inline` — reported separately from the script-level loosening because inline styles are a far smaller exposure than inline scripts.
`cspUnsafeEval`	boolean	no	`CSP` permits `unsafe-eval`.
`cspUnsafeInline`	boolean	no	`CSP` permits `unsafe-inline` (a common XSS-defeating loosening).
`cspWildcard`	boolean	no	`CSP` uses a wildcard source (`*`) in a fetch directive.
`grade`	string	no	A..F letter grade over the weighted quality checks below.
`hsts`	boolean	no	`Strict-Transport-Security` present at all.
`hstsIncludeSubdomains`	boolean	no	`HSTS` carries `includeSubDomains`.
`hstsMaxAge`	integer (int64)	no	`HSTS` `max-age` in seconds (0 when absent/unparseable).
`https`	boolean	no	Whether the audited target was reached over HTTPS.
`notes`	array<string>	no	Human-readable quality issues (folded into the report findings).
`permissionsPolicy`	boolean	no	`Permissions-Policy` (feature policy) present.
`referrerPolicy`	boolean	no	`Referrer-Policy` present.
`xContentTypeOptions`	boolean	no	`X-Content-Type-Options: nosniff`.
`xFrameOptions`	boolean	no	`X-Frame-Options` present (clickjacking defense; CSP `frame-ancestors` is the modern form but XFO is still widely honoured).

SeoAnalysisMode

Type: string one of "source-html"

SeoCategory

Type: string one of "indexability", "searchPresentation", "siteLinkHygiene", "structuredData", "content", "socialPreview", "aiReadiness", "trust", "performance", "other"

SeoCheck

One stable, machine-comparable technical SEO check.

Properties
Name	Type	Required
`category`	SeoCategory	no
`evidence`	array<string>	no
`id`	string	no
`message`	string	no
`recommendation`	string	no
`severity`	SeoSeverity	no
`status`	SeoCheckStatus	no

SeoCheckChange

One stable technical SEO check's transition between comparable snapshots.

Properties
Name	Type	Required	Description
`afterStatus`	null \| SeoCheckStatus	no
`beforeStatus`	null \| SeoCheckStatus	no
`id`	string	yes
`kind`	string	yes	`introduced` / `resolved` / `status-changed`.

SeoCheckStatus

Type: string one of "pass", "fail", "warning", "opportunity", "notApplicable"

SeoIndexPresence

Actual presence in a public search engine's index. Source-HTML Site Audit has no authenticated engine evidence, so it must never infer this value from HTTP, robots, canonical, or sitemap signals.

Type: string one of "notMeasured"

SeoIndexability

Technical indexing eligibility inferred from fetched page signals. In particular, `Indexable` does not mean a search engine has indexed the URL.

Type: string one of "indexable", "excluded", "blocked", "unknown"

SeoMetrics

Advisory source-content metrics. None of these counts is a ranking factor or directly changes the technical score.

Properties
Name	Type	Required
`emptyAnchorCount`	integer	no
`emptyHeadingCount`	integer	no
`externalLinkCount`	integer	no
`hasByline`	boolean	no
`headingCount`	integer	no
`headingOrderSkips`	integer	no
`hreflangCount`	integer	no
`imageCount`	integer	no
`imagesMissingAlt`	integer	no
`internalLinkCount`	integer	no
`paragraphCount`	integer	no
`visibleDateCount`	integer	no
`wordCount`	integer	no

SeoReport

Separately versioned technical search-readiness result. This is not a ranking score and never alters the legacy `AuditReport.score`.

Properties
Name	Type	Required
`analysisMode`	SeoAnalysisMode	no
`checks`	array<SeoCheck>	no
`complete`	boolean	no
`expectedIndexable`	boolean	no
`indexPresence`	SeoIndexPresence	no
`indexability`	SeoIndexability	no
`metrics`	SeoMetrics	no
`score`	integer \| null (int32)	no
`scoreModelVersion`	integer (int32)	no
`sitemap`	SeoSitemapSummary	no
`socialPreview`	SocialPreviewSummary	no
`structuredData`	StructuredDataSummary	no

SeoSeverity

Type: string one of "high", "medium", "low", "info"

SeoSitemapSummary

Compact, additive sitemap evidence for the audited page. This describes the already-fetched conventional sitemap documents only; it does not claim a whole-site crawl when an index or another declared sitemap was not fetched.

Properties
Name	Type	Required
`complete`	boolean	no
`documentsEvaluated`	integer	no
`entriesEvaluated`	integer	no
`membership`	SitemapMembership	no

SiteConfig

Site configuration for crawling. Equivalent to Kotlin `SiteProfile.Config`.

Properties
Name	Type	Required	Description
`allowUrlWithQuery`	boolean	no
`pageBodyCssSelector`	string	no
`sitemapsOnly`	boolean	no
`url`	string \| null	no	URL for the site configuration. Serializes as empty string if None.

SiteCreation

Site creation response. Equivalent to Kotlin `SiteCreation`.

Properties
Name	Type	Required	Description
`siteId`	string (uuid)	yes
`siteSecret`	string (uuid)	yes

Used by: POST /sites

SiteIndexSummary

Site index summary response. Equivalent to Kotlin `SiteIndexSummary`.

Properties
Name	Type	Required
`documents`	array<string>	yes
`failed`	array<string>	yes
`siteId`	string (uuid)	yes
`siteSecret`	string (uuid)	yes
`successCount`	integer	yes

Used by: POST /sites/rss, PUT /sites/{siteId}/rss, PUT /sites/{siteId}/xml

SitePage

Page content for search indexing. Equivalent to Kotlin `SitePage`.

Properties
Name	Type	Required
`body`	string	yes
`labels`	array<string>	no
`thumbnail`	string	yes
`title`	string	yes
`url`	string	yes

SitePageInput

Input DTO for page upsert (PUT /sites/{siteId}/pages). Matches the Kotlin `SitePage` input structure with optional fields.

Properties
Name	Type	Required
`body`	string \| null	no
`id`	string \| null	no
`labels`	array<string>	no
`siteId`	string \| null (uuid)	no
`thumbnail`	string \| null	no
`title`	string \| null	no
`updated`	string \| null	no
`url`	string \| null	no

Used by: PUT /sites/{siteId}/pages, PUT /sites/{siteId}/pages/{pageId}

SiteProfile

Site profile configuration. Equivalent to Kotlin `SiteProfile`.

Properties
Name	Type	Required
`configs`	array<SiteConfig>	no
`email`	string	no
`id`	string (uuid)	yes
`secret`	string (uuid)	yes

Used by: GET /sites/{siteId}/profile, PUT /sites/{siteId}/profile

SiteProfileConfigInput

Site profile config input (matching Kotlin's SiteProfile.Config for input)

Properties
Name	Type	Required
`allowUrlWithQuery`	boolean	no
`pageBodyCssSelector`	string	no
`sitemapsOnly`	boolean	no
`url`	string	no

SiteProfileCreation

Site profile creation request.

Properties
Name	Type	Required	Description
`configs`	array<SiteProfileConfigInput>	no
`email`	string	no

Used by: POST /sites

SiteProfileUpdate

Site profile update request. Matches Kotlin `SiteProfileUpdate` which includes secret for updating credentials.

Properties
Name	Type	Required	Description
`configs`	array<SiteProfileConfigInput>	no
`email`	string \| null	no
`secret`	string \| null (uuid)	no	New secret for the site (can be used to rotate credentials)

Used by: PUT /sites/{siteId}/profile

SitemapMembership

Whether the audited page's effective URL was observed in the bounded sitemap evidence available to the one-page audit. `Unknown` is deliberately distinct from `Absent`: only a complete, valid sitemap corpus can prove absence.

Type: string one of "present", "absent", "duplicate", "unknown"

SitesCrawlStatus

Collection of crawl statuses. Equivalent to Kotlin `SitesCrawlStatus`.

Properties
Name	Type	Required	Description
`sites`	array<CrawlStatus>	yes

Used by: POST /sites/crawl, GET /sites/crawl/status, PUT /sites/crawl/status

SnapshotDiff

Properties
Name	Type	Required	Description
`after`	SnapshotMeta	yes
`before`	SnapshotMeta	yes
`cdnChange`	null \| CdnChange	no
`changes`	array<UrlChange>	yes
`scoreDelta`	integer (int32)	yes	`after.score - before.score`.
`seoCheckChanges`	array<SeoCheckChange>	no	Stable-ID SEO check transitions. `None` means the snapshots' SEO analyses are not comparable; `Some([])` means they are comparable and no check status changed.
`seoScoreDelta`	integer \| null (int32)	no	`after.seoScore - before.seoScore`, only for complete scored reports using the same SEO model, expectation, and analysis mode. Old or incomparable snapshots omit it.
`unchanged`	integer	yes	Common paths whose probe was byte-for-byte unchanged.

Used by: GET /audit/diff

SnapshotMeta

Properties
Name	Type	Required	Description
`capturedAt`	integer (int64)	yes
`host`	string	yes
`id`	string	yes
`label`	string \| null	no
`score`	integer (int32)	yes
`seoScore`	integer \| null (int32)	no	Technical SEO score, when this snapshot contains a complete scored SEO analysis. Kept separate from the frozen compatibility score.
`seoScoreModelVersion`	integer \| null (int32)	no
`target`	string	yes

SocialPreviewSummary

Properties
Name	Type	Required
`openGraphDescription`	boolean	no
`openGraphImage`	boolean	no
`openGraphTitle`	boolean	no
`openGraphUrl`	boolean	no
`twitterCard`	boolean	no
`twitterDescription`	boolean	no
`twitterImage`	boolean	no
`twitterTitle`	boolean	no

StartEmailRequest

Properties
Name	Type	Required	Description
`email`	string	yes

Used by: POST /audit/watches/{id}/notifications/email

Stats

Properties
Name	Type	Required	Description
`analyticsStats`	null \| AnalyticsStatsSummary	no
`buildNumber`	string	yes	CI build number injected via `BUILD_NUMBER` env var at runtime. CODEX Directive 3 contract: field is named `buildNumber` in public JSON. Pinned by `api.hurl:77`.
`retentionSweep`	null \| SweepSummary	no
`scmHash`	string	yes	Source-control hash (git commit) injected via `SCM_HASH` env var at runtime. CODEX Directive 3 contract: this field is named `scmHash` in the public JSON. Do not rename. `api.hurl:78` pins this as a published API promise.
`status`	string	yes	Service status — always `"ok"` if this endpoint responds.
`uptimeS`	integer (int64)	yes	Process uptime in seconds since api started.
`version`	string	yes	Crate version (from Cargo manifest).

Used by: GET /stats.json

StoredSnapshot

An immutable, labelled audit snapshot.

Properties
Name	Type	Required	Description
`capturedAt`	integer (int64)	yes	Capture time, epoch milliseconds.
`id`	string	yes
`label`	string \| null	no
`report`	AuditReport	yes

Used by: POST /audit/snapshots, GET /audit/snapshots/{id}

StructuredDataSummary

Properties
Name	Type	Required	Description
`articleItems`	integer	no
`articleOpportunities`	array<string>	no	Missing recommended Article-family properties, surfaced as opportunities.
`articleWarnings`	array<string>	no	Malformed values for present Article-family properties. Missing recommended properties are tracked separately as advisory opportunities.
`blocks`	integer	no
`breadcrumbIssues`	array<string>	no	Objective BreadcrumbList structure errors (required properties/order).
`breadcrumbLists`	integer	no
`commerceOpportunities`	array<string>	no	Missing context-dependent rich-result property groups. Organization has no universally required group and therefore creates no omission issue.
`commerceWarnings`	array<string>	no	Malformed values on present Product, SoftwareApplication, Organization, or Offer properties. These remain advisory so adding the validation does not alter the versioned score model.
`invalidBlocks`	integer	no
`invalidBreadcrumbLists`	integer	no
`items`	integer	no
`offerItems`	integer	no
`offerVisibilityWarnings`	array<string>	no	Material Offer literals observed only in strongly hidden source nodes.
`organizationItems`	integer	no
`pageUrlSignalsTruncated`	boolean	no	True when more distinct current-page URL signals were present than can be retained safely. The parent report is then incomplete and unscored.
`productItems`	integer	no
`softwareApplicationItems`	integer	no
`truncated`	boolean	no	True when the bounded JSON-LD walk reached its nesting ceiling. The parent SEO report is then incomplete and deliberately unscored.
`types`	array<string>	no
`validBlocks`	integer	no

SweepSummary

Published on `/stats.json` as `retentionSweep` so the `redis-capacity` alarm can tell a stalled sweep - the only thing bounding visit growth - from a healthy one.

Properties
Name	Type	Required
`error`	string \| null	no
`lastOkUnixMs`	integer \| null (int64)	no
`lastRunUnixMs`	integer (int64)	yes
`purged`	integer	yes
`sitesFailed`	integer	yes
`truncated`	boolean	yes

TlsFailureReason

Sanitized machine-readable TLS evidence; never parsed from URL-bearing errors.

Type: string one of "expired", "notYetValid", "hostMismatch", "unknownIssuer", "certificateInvalid", "dnsFailure", "connectFailure", "handshakeFailure", "timeout", "invalidServerName", "malformedCertificate", "admissionRejected" …

TlsInfo

TLS handshake + leaf-certificate facts for an HTTPS origin, captured by a dedicated pinned handshake (see [`crate::audit::tls`]). A tractable subset of what SSL Labs reports — enough for QA (expiry, key strength, hostname match, protocol support) without the heavy machinery (full cipher enumeration, per-client handshake simulation, active vulnerability probes) tracked in the backlog. Deliberately value-stable (no per-connection nonces) so re-audits diff cleanly. Absent for `http://` targets or when the handshake failed.

Properties
Name	Type	Required	Description
`alpnProtocol`	string \| null	no	The ALPN protocol the server selected when offered `h2` and `http/1.1` (`h2` means HTTP/2). Absent when the server selected none, which means HTTP/1.1, and in reports captured before the handshake offered ALPN.
`capturedAt`	integer \| null (int64)	no	Capture time for deterministic validity classification of retained reports.
`chain`	array<ChainCert>	no	The additional certificates beyond the leaf (intermediates / roots).
`chainLength`	integer	no	Number of certificates the server presented (leaf + intermediates).
`cipherSuite`	string \| null	no	The negotiated cipher suite (e.g. `TLS13_AES_256_GCM_SHA384`).
`configurationGrade`	string \| null	no	Protocol/configuration grade independent of certificate trust, hostname, and validity. `grade` remains the legacy combined result.
`daysRemaining`	integer (int64)	no	Whole days until `notAfter` (negative once expired), from capture time.
`grade`	string \| null	no	A conservative TLS-config letter grade (A..F) over the subset we test — NOT the full Qualys rating (which needs cipher/legacy-protocol/vuln probing; see the backlog).
`hostMatch`	boolean \| null	no	Whether the leaf covers the audited hostname (SAN, wildcard-aware).
`issuer`	string \| null	no	Issuer common-name / organization, best-effort.
`keyBits`	integer \| null (int32)	no	Leaf public-key strength in bits (RSA modulus / EC field size).
`keyType`	string \| null	no	Leaf public-key type: `EC` / `RSA` / `Ed25519`.
`notAfter`	integer (int64)	no	The leaf certificate's `notAfter`, epoch seconds.
`notAfterUtc`	string \| null	no
`notBefore`	integer (int64)	no	The leaf certificate's `notBefore`, epoch seconds.
`notBeforeUtc`	string \| null	no
`protocol`	string \| null	no	The highest TLS version negotiated (e.g. `TLSv1.3`).
`sans`	array<string>	no	DNS and IP Subject Alternative Names on the leaf, rendered as strings.
`sha256`	string \| null	no
`signatureAlgorithm`	string \| null	no	Leaf certificate signature algorithm (e.g. `ecdsa-with-SHA384`).
`subject`	string \| null	no	Subject common-name, best-effort.
`supportedProtocols`	array<string>	no	Which TLS versions completed a handshake (subset of `TLSv1.2`,`TLSv1.3`).
`trustFailureReason`	null \| TlsFailureReason	no
`trustState`	TlsTrustState	no
`validNow`	boolean	no	True when the certificate is currently inside its validity window.

TlsInspectionEvidence

Scope of one dedicated TLS inspection, independent of the HTTP response.

Properties
Name	Type	Required
`address`	string \| null	no
`capturedAt`	integer (int64)	yes
`complete`	boolean	yes
`failureReason`	null \| TlsFailureReason	no
`host`	string	yes
`port`	integer (int32)	yes

TlsTrustState

Whether the presented certificate chain is trusted for the audited hostname by the bundled public WebPKI roots at capture time.

Type: string one of "trusted", "untrusted", "unknown"

TlsWatchStatus

Public latest-run evidence excludes the private notification dedup state.

Properties
Name	Type	Required
`at`	integer (int64)	yes
`host`	string	yes
`httpTlsFailure`	boolean	yes
`inspection`	null \| TlsInspectionEvidence	no
`tls`	null \| TlsInfo	no

Used by: GET /audit/watches/{id}/tls

TransportEvidence

How the page travels: negotiated HTTP version, advertised HTTP/3, and compression.

Properties
Name	Type	Required	Description
`alpnProtocol`	string \| null	no	The ALPN protocol the TLS inspection handshake negotiated after offering `h2` and `http/1.1`. Absent for `http://`, a failed handshake, or a server that selects no protocol (which means HTTP/1.1).
`altSvcProtocols`	array<string>	no	Protocol ids the page response's `Alt-Svc` header advertises, in order. The header itself is not reported, so its per-response parameters never show up as a header change in snapshot diffs.
`compression`	null \| CompressionEvidence	no
`http3Advertised`	boolean	no	The page response's `Alt-Svc` header advertises HTTP/3 (`h3` or a draft `h3-*` id).

TrendSample

One point on a watch's score trend.

Properties
Name	Type	Required	Description
`at`	integer (int64)	yes	When the run started, epoch milliseconds.
`score`	integer (int32)	yes	The run's legacy compatibility score.

Used by: GET /audit/watches/{id}/trend

TrialStatus

Properties
Name	Type	Required	Description
`activeWatches`	integer	yes
`allowedHosts`	array<string>	yes
`automaticTlsChecksEnabled`	boolean	yes	Whether this deployment enables automatic trial TLS checks.
`dailyReportLimit`	integer (int32)	yes
`expiresAt`	integer (int64)	yes	Exclusive access expiry, in epoch milliseconds.
`issuedAt`	integer (int64)	yes	Issuance time, in epoch milliseconds (storage uses epoch seconds).
`nextResetAt`	integer (int64)	yes	Next UTC midnight, in epoch milliseconds.
`remainingToday`	integer (int32)	yes
`trialId`	string	yes
`watchLimit`	integer	yes

Used by: GET /audit/trial

UpdateAsset

JSON body to edit an asset in place. Every field is optional — only the provided fields change. A `description` of `""` clears it; omitting it leaves it untouched. Ids/owner/createdAt are immutable.

Properties
Name	Type	Required	Description
`bookingFields`	array<BookingFieldDef>	no	Replace the whole custom-field set (send `[]` to clear; omit to leave as-is).
`currency`	string \| null	no
`description`	string \| null	no
`kind`	string \| null	no
`name`	string \| null	no
`policy`	null \| BookingPolicy	no
`promoCodes`	array<PromoCode>	no	Replace the whole promo-code set (send `[]` to clear; omit to leave as-is).
`timezone`	string \| null	no

Used by: PATCH /assets/owners/{ownerId}/assets/{assetId}

UpdateWindow

JSON body to edit a window's `cost` and/or `capacity` in place (its time range is immutable — delete + re-add, or reschedule bookings, to move a slot). `capacity` may not drop below the window's current active-booking count.

Properties
Name	Type	Required	Description
`capacity`	integer \| null (int32)	no
`cost`	number \| null (double)	no

Used by: PATCH /assets/owners/{ownerId}/assets/{assetId}/windows/{windowId}

UrlChange

One URL's change between two snapshots.

Properties
Name	Type	Required	Description
`afterClass`	string \| null	no
`beforeClass`	string \| null	no
`details`	array<string>	no
`kind`	string	yes	`appeared` / `disappeared` / `broke` / `fixed` / `redirected` / `content-changed` / `header-changed` / `size-changed` / `status-changed`.
`path`	string	yes

User

Properties
Name	Type	Required	Description
`id`	integer (int64)	yes	Unique user ID
`username`	string	yes	Username

VerifyEmailRequest

Properties
Name	Type	Required	Description
`token`	string	yes

Used by: POST /audit/watches/{id}/notifications/email/verify

ViewerAsset

An asset returned to a read-only Viewer. Promo codes are anonymous discount capabilities and therefore stay on root/operational surfaces.

Properties
Name	Type	Required
`bookingFields`	array<BookingFieldDef>	no
`createdAt`	integer (int64)	yes
`currency`	string	yes
`description`	string \| null	no
`id`	string	yes
`kind`	string	yes
`name`	string	yes
`policy`	null \| BookingPolicy	no
`timezone`	string	yes

ViewerAssetWithWindows

Properties
Name	Type	Required
`asset`	ViewerAsset	yes
`windowCount`	integer (int32)	yes
`windows`	array<ViewerWindow>	yes

ViewerReservation

A booking visible to a read-only manager. All operational booking data is retained except the reservation bearer that can mutate the booking.

Properties
Name	Type	Required
`assetId`	string	yes
`consumer`	string	yes
`cost`	number (double)	yes
`currency`	string	yes
`fields`	map<string, string>	no
`holdExpiresAt`	integer \| null (int64)	no
`note`	string \| null	no
`quantity`	integer (int32)	yes
`reservedAt`	integer (int64)	yes
`status`	ReservationStatus	yes
`windowId`	string	yes

ViewerReservationRow

Properties
Name	Type	Required
`assetId`	string	yes
`assetName`	string	yes
`end`	integer (int64)	yes
`reservation`	ViewerReservation	yes
`start`	integer (int64)	yes
`windowId`	string	yes

ViewerWindow

A manager window whose embedded reservations cannot be used as public cancel/confirm/reschedule/modify capabilities.

Properties
Name	Type	Required
`assetId`	string	yes
`capacity`	integer (int32)	yes
`cost`	number (double)	yes
`end`	integer (int64)	yes
`id`	string	yes
`remaining`	integer (int32)	yes
`reservations`	array<ViewerReservation>	yes
`start`	integer (int64)	yes
`waitlisted`	integer (int32)	yes

ViewerWindowsPage

Properties
Name	Type	Required
`offset`	integer (int32)	yes
`total`	integer (int32)	yes
`windows`	array<ViewerWindow>	yes

Visit

`/visit.json` verdict.

Properties
Name	Type	Required	Description
`asName`	string	yes	Network owner (ASN org) — explains datacenter / proxy bot verdicts.
`asNumber`	integer (int32)	yes
`country`	string	yes
`countryCode`	string	yes
`ip`	string	yes	Client IP used for the verdict (Envoy-derived, or `queryIP` override).
`reasons`	array<string>	yes	Human-readable signals behind the score.
`score`	integer (int32)	yes	Unified bot-likelihood, 0 (human) .. 100 (bot).
`verdict`	string	yes	`human` \| `suspect` \| `bot`.

Used by: POST /visit.json

VisitDay

One UTC day's counts for the time series.

Properties
Name	Type	Required	Description
`bot`	integer (int64)	yes
`day`	string	yes	`YYYY-MM-DD` (UTC).
`human`	integer (int64)	yes
`visits`	integer (int64)	yes

VisitStats

Aggregated visit analytics for one tracked site over a window — returned by [`Metering::visit_stats`] / `GET /visit/stats.json`.

Properties
Name	Type	Required	Description
`byDay`	array<VisitDay>	yes
`engagement`	null \| EngagementAggregate	no
`outbound`	null \| OutboundAggregate	no
`since`	string	yes	RFC3339 lower bound of the window.
`siteId`	string	yes	The tracked site id (serialized as `siteId`).
`topBrowsers`	array<CountRow>	yes	Top visitor browsers in the window, classified from the User-Agent (descending), capped at [`TOP_N`].
`topCities`	array<CountRow>	yes	Top visitor cities in the window (descending), capped at [`TOP_N`]; unknown (unresolved) cities are excluded.
`topCountries`	array<CountRow>	yes	Top visitor countries (GeoIP ISO codes) in the window (descending), capped at [`TOP_N`]; unknown (unresolved) countries are excluded.
`topDevices`	array<CountRow>	yes	Top visitor device types (Desktop / Mobile / Tablet) in the window, classified from the User-Agent (descending), capped at [`TOP_N`].
`topJa3`	array<CountRow>	yes	Top TLS fingerprints (JA3) in the window — a strong automation signal. Aggregate only, with a [`JA3_MIN_VISITORS`] k-anonymity floor; empties excluded. Shown as-is (not pseudonymised) to stay threat-intel-matchable.
`topNetworks`	array<CountRow>	yes	Top visitor networks (GeoIP ASN organization) in the window (descending), capped at [`TOP_N`]; unknown (unresolved) networks are excluded.
`topPages`	array<CountRow>	yes	Most-visited paths in the window (descending), capped at [`TOP_N`].
`topReferrers`	array<CountRow>	yes	Top external referrer hosts in the window (descending), capped at [`TOP_N`]; direct / same-site (empty-referrer) visits are excluded.
`topSystems`	array<CountRow>	yes	Top visitor operating systems in the window, classified from the User-Agent (descending), capped at [`TOP_N`].
`totals`	VisitTotals	yes
`vitals`	null \| VitalsAggregate	no

VisitStatsResponse

HTTP analytics response: aggregates plus current per-request configuration. Configuration must stay outside the report cache.

Type: VisitStats | object

Used by: GET /visit/stats.json

VisitTotals

Verdict totals for one site over a window.

Properties
Name	Type	Required	Description
`bot`	integer (int64)	yes
`human`	integer (int64)	yes
`newVisits`	integer (int64)	yes	Visits by a first-time identified visitor (Option B `loxal_vid` cookie) in the window — the "new" side of the new-vs-returning split. Zero for cookieless (Option A) sites, which issue no visitor id.
`relay`	integer (int64)	yes	Visits via iCloud Private Relay (privacy-preserving real humans).
`returningVisits`	integer (int64)	yes	Visits by a visitor seen before (Option B cookie) in the window — the "returning" side of the split.
`suspect`	integer (int64)	yes
`tor`	integer (int64)	yes	Visits over Tor exit nodes (anonymized) in the window.
`uniqueVisitors`	integer (int64)	yes	Distinct visitors (by client IP, cookieless) in the window.
`visits`	integer (int64)	yes	Total page views — one per recorded beacon — in the window.

VitalsAggregate

Aggregate Core Web Vitals over the same window as [`VisitStats`]. Absent (`None`) when the window contains zero opt-in samples for a metric. `P75` is Google's canonical field-metric summary — it reflects the 75th-percentile experience across all sampled visits, which is what Search Console reports.

Properties
Name	Type	Required	Description
`p75Cls`	number \| null (double)	no	P75 Cumulative Layout Shift (unitless) — Google: < 0.1 good, < 0.25 needs improvement, otherwise poor.
`p75InpMs`	number \| null (double)	no	P75 Interaction to Next Paint (ms) — Google: < 200 good, < 500 needs improvement, otherwise poor.
`p75LcpMs`	number \| null (double)	no	P75 Largest Contentful Paint (ms) — Google: < 2500 good, < 4000 needs improvement, otherwise poor.
`p75TtfbMs`	number \| null (double)	no	P75 Time to First Byte (ms) — Google (informational): < 800 good, < 1800 needs improvement.
`samples`	integer (int64)	yes	Total number of visits in the window that contributed at least one vitals metric. When zero, the four P75 fields are all `None`.

VoucherQuotaStatus

`GET /audit/quota`: the paid reports a Site Audit voucher has left.

Properties
Name	Type	Required	Description
`remaining`	integer (int32)	yes	Paid reports the voucher can start now; credits reserved by audits in progress are not counted.
`total`	integer (int32)	yes	Paid reports the voucher was issued with.

Used by: GET /audit/quota

WaitlistEntry

A consumer's place in a window's waitlist. `id` is their capability to leave the queue. When a booking on the window is cancelled and frees a seat, the head of the queue is auto-promoted into a [hold] and a `waitlist.promote` event fires (so the operator can act on it). [hold]: AssetStore::hold

Properties
Name	Type	Required	Description
`assetId`	string	yes
`consumer`	string	yes
`fields`	map<string, string>	no	Custom booking-field values carried onto the promoted hold (empty = none).
`id`	string	yes
`joinedAt`	integer (int64)	yes
`note`	string \| null	no
`quantity`	integer (int32)	no	Seats to promote into when this ticket reaches the head (default 1). The head is only promoted when at least this many seats free.
`windowId`	string	yes

Used by: POST /assets/asset/{assetId}/windows/{windowId}/waitlist

WatchAlert

A regression alert recorded (and optionally webhook'd) for a watch.

Properties
Name	Type	Required	Description
`at`	integer (int64)	yes	When the run that raised the alert started, epoch milliseconds.
`kind`	string	yes	`score-drop` / `score-below-minimum` / `seo-score-drop` / `broke` / `cdn-removed` / `unreachable` / `cert-expiry`.
`message`	string	yes	What regressed, in words.
`scoreAfter`	integer \| null (int32)	no	The legacy compatibility score of the run that raised the alert.
`scoreBefore`	integer \| null (int32)	no	The legacy compatibility score before the regression, when known.

Used by: GET /audit/watches/{id}/alerts

WatchMode

Full audits remain the default for old stored watches and existing clients.

Type: string one of "full", "tls"

Used by: POST /audit/watches

Webhook

An outbound event webhook: the owner asks us to POST a JSON payload to `url` whenever a matching event fires on their assets. `id` doubles as the delete capability. `url` is SSRF-guarded at registration *and* at send.

Properties
Name	Type	Required	Description
`createdAt`	integer (int64)	yes
`events`	array<string>	yes	Event selectors: `"*"` (all), a category (`booking`/`asset`/`window`/ `owner`), or an exact action (`reserve`, `cancel`, `asset.create`, …).
`id`	string	yes
`url`	string	yes	Sanitized target URL (http/https, web port, credentials stripped).

Used by: GET /assets/owners/{ownerId}/webhooks, POST /assets/owners/{ownerId}/webhooks

WhoAmI

The resolved identity behind a manager-surface token — lets a client tailor its UI to the caller's authority without leaking the owner secret.

Properties
Name	Type	Required	Description
`isOwner`	boolean	yes	True iff the caller holds the root ownerId.
`role`	Role	yes

Used by: GET /assets/owners/{ownerId}/whoami

Whois

Whois response schema — stable across all data-source backends. **Why all 12 fields are present on every response, even when 5 of them are not populated under the current default backend:** - The default data source is DB-IP Lite (CC BY 4.0). It carries 7 of these 12 fields with real values; the remaining 5 (`code` postal, `cityId`, `countryState`, `countryStateId`, `timeZone`) come back with the `EXTENDED_FIELD_HINT` / `EXTENDED_FIELD_HINT_ID` sentinel — telling the consumer the field is part of the schema but only populated for Pro / Enterprise customers. - The 5 hinted fields are positioned to customers as **extended fields available on request** for Pro / Enterprise tiers (see `sites/www/product/ip-intelligence.html`, which also hosts the folded `#pricing` section). When a paying customer triggers a MaxMind GeoIP2 license purchase, the data-source path for that key fills in those fields with real values — no schema change required, no consumer breakage. CODEX Directive 3 wins via the response shape staying constant.

Properties
Name	Type	Required	Description
`asName`	string	yes	Autonomous System name (ISP/organization)
`asNumber`	integer (int32)	yes	Autonomous System number
`city`	string	yes	City name
`cityId`	integer (int64)	yes	GeoNames city ID. Extended field — `-1` (`EXTENDED_FIELD_HINT_ID`) under the default backend; real positive integer on the upgrade.
`code`	string	yes	Postal/ZIP code. Extended field — populated for Pro / Enterprise customers with the paid MaxMind GeoIP2 backend. Default backend returns the [`EXTENDED_FIELD_HINT`] sentinel.
`country`	string	yes	Country name
`countryCode`	string	yes	ISO 3166-1 alpha-2 country code
`countryId`	integer (int64)	yes	GeoNames country ID
`countryState`	string	yes	State / province ISO code (e.g. "NSW"). Extended field — see [`EXTENDED_FIELD_HINT`].
`countryStateId`	integer (int64)	yes	GeoNames state / province ID. Extended field — see [`EXTENDED_FIELD_HINT_ID`].
`ip`	string	yes	Client IP address
`timeZone`	string	yes	IANA time zone identifier. Extended field — see [`EXTENDED_FIELD_HINT`].

Used by: GET /whois.json

Window

A utilization window as returned to the manager: the slot plus its live booking state (`remaining` seats + the reservations on it).

Properties
Name	Type	Required	Description
`assetId`	string	yes
`capacity`	integer (int32)	yes	How many can book this slot (default 1).
`cost`	number (double)	yes	Cost to use the asset for this window, in the asset's `currency`.
`end`	integer (int64)	yes	Slot end, epoch-ms UTC (exclusive); must be `> start`.
`id`	string	yes
`remaining`	integer (int32)	yes	Seats still available = `capacity` − active bookings.
`reservations`	array<Reservation>	yes	The bookings on this window (active + cancelled; `status` distinguishes).
`start`	integer (int64)	yes	Slot start, epoch-ms UTC (inclusive).
`waitlisted`	integer (int32)	no	How many consumers are queued on this window's waitlist.

Used by: POST /assets/owners/{ownerId}/assets/{assetId}/windows, PATCH /assets/owners/{ownerId}/assets/{assetId}/windows/{windowId}

WindowsPage

A page of an asset's windows (owner drill-down; `total` is the full count).

Properties
Name	Type	Required
`offset`	integer (int32)	yes
`total`	integer (int32)	yes
`windows`	array<Window>	yes

WindowsPageResponse

Role-dependent serialization for one asset's window page. Dispatchers need reservation IDs for their `Book` capability; viewers do not receive them.

Type: WindowsPage | ViewerWindowsPage

Used by: GET /assets/owners/{ownerId}/assets/{assetId}/windows

echo

GET /echo.json

entropy

GET /entropy.json

encoding

GET /encoding.json

whois

GET /whois.json

inspect

GET /inspect.json

curl

GET /curl.json

audit

GET /audit.json

GET /audit/crawl

GET /audit/diff

GET /audit/quota

POST /audit/snapshots

GET /audit/snapshots/{id}

GET /audit/snapshots/{id}/suite.hurl

GET /audit/trial

POST /audit/watches

GET /audit/watches/{id}

DELETE /audit/watches/{id}

GET /audit/watches/{id}/alerts

GET /audit/watches/{id}/notifications/email

POST /audit/watches/{id}/notifications/email

DELETE /audit/watches/{id}/notifications/email

POST /audit/watches/{id}/notifications/email/verify

POST /audit/watches/{id}/run

GET /audit/watches/{id}/tls

GET /audit/watches/{id}/trend

test

GET /test

stats

GET /stats.json

crawler

POST /sites/crawl

GET /sites/crawl/status

PUT /sites/crawl/status

POST /sites/{siteId}/crawl

POST /sites/{siteId}/recrawl

sites

POST /sites

PUT /sites/flush

POST /sites/rss

GET /sites/{siteId}

DELETE /sites/{siteId}

GET /sites/{siteId}/autocomplete

GET /sites/{siteId}/har

GET /sites/{siteId}/pages

PUT /sites/{siteId}/pages

DELETE /sites/{siteId}/pages

PUT /sites/{siteId}/pages/{pageId}

DELETE /sites/{siteId}/pages/{pageId}

PUT /sites/{siteId}/pages/{pageId}/backdate

GET /sites/{siteId}/profile

PUT /sites/{siteId}/profile

PUT /sites/{siteId}/rss

GET /sites/{siteId}/search

PUT /sites/{siteId}/xml

email

POST /sites/{siteId}/email/setup-info

pages

GET /pages/{id}

assets

GET /assets/asset/{assetId}

GET /assets/asset/{assetId}/calendar.ics

POST /assets/asset/{assetId}/windows/{windowId}/hold

POST /assets/asset/{assetId}/windows/{windowId}/reserve

POST /assets/asset/{assetId}/windows/{windowId}/waitlist

DELETE /assets/asset/{assetId}/windows/{windowId}/waitlist/{ticketId}

POST /assets/owners

GET /assets/owners/{ownerId}/assets

POST /assets/owners/{ownerId}/assets

PATCH /assets/owners/{ownerId}/assets/{assetId}

DELETE /assets/owners/{ownerId}/assets/{assetId}

POST /assets/owners/{ownerId}/assets/{assetId}/availability

GET /assets/owners/{ownerId}/assets/{assetId}/windows

POST /assets/owners/{ownerId}/assets/{assetId}/windows

GET `/echo.json`

GET `/entropy.json`

GET `/encoding.json`

GET `/whois.json`

GET `/inspect.json`

GET `/curl.json`

GET `/audit.json`

GET `/audit/crawl`

GET `/audit/diff`

GET `/audit/quota`

POST `/audit/snapshots`

GET `/audit/snapshots/{id}`

GET `/audit/snapshots/{id}/suite.hurl`

GET `/audit/trial`

POST `/audit/watches`

GET `/audit/watches/{id}`

DELETE `/audit/watches/{id}`

GET `/audit/watches/{id}/alerts`

GET `/audit/watches/{id}/notifications/email`

POST `/audit/watches/{id}/notifications/email`

DELETE `/audit/watches/{id}/notifications/email`

POST `/audit/watches/{id}/notifications/email/verify`

POST `/audit/watches/{id}/run`

GET `/audit/watches/{id}/tls`

GET `/audit/watches/{id}/trend`

GET `/test`

GET `/stats.json`

POST `/sites/crawl`

GET `/sites/crawl/status`

PUT `/sites/crawl/status`

POST `/sites/{siteId}/crawl`

POST `/sites/{siteId}/recrawl`

POST `/sites`

PUT `/sites/flush`

POST `/sites/rss`

GET `/sites/{siteId}`

DELETE `/sites/{siteId}`

GET `/sites/{siteId}/autocomplete`

GET `/sites/{siteId}/har`

GET `/sites/{siteId}/pages`

PUT `/sites/{siteId}/pages`

DELETE `/sites/{siteId}/pages`

PUT `/sites/{siteId}/pages/{pageId}`

DELETE `/sites/{siteId}/pages/{pageId}`

PUT `/sites/{siteId}/pages/{pageId}/backdate`

GET `/sites/{siteId}/profile`

PUT `/sites/{siteId}/profile`

PUT `/sites/{siteId}/rss`

GET `/sites/{siteId}/search`

PUT `/sites/{siteId}/xml`

POST `/sites/{siteId}/email/setup-info`

GET `/pages/{id}`

GET `/assets/asset/{assetId}`

GET `/assets/asset/{assetId}/calendar.ics`

POST `/assets/asset/{assetId}/windows/{windowId}/hold`

POST `/assets/asset/{assetId}/windows/{windowId}/reserve`

POST `/assets/asset/{assetId}/windows/{windowId}/waitlist`

DELETE `/assets/asset/{assetId}/windows/{windowId}/waitlist/{ticketId}`

POST `/assets/owners`

GET `/assets/owners/{ownerId}/assets`

POST `/assets/owners/{ownerId}/assets`

PATCH `/assets/owners/{ownerId}/assets/{assetId}`

DELETE `/assets/owners/{ownerId}/assets/{assetId}`

POST `/assets/owners/{ownerId}/assets/{assetId}/availability`

GET `/assets/owners/{ownerId}/assets/{assetId}/windows`

POST `/assets/owners/{ownerId}/assets/{assetId}/windows`

DELETE `/assets/owners/{ownerId}/assets/{assetId}/windows`

PATCH `/assets/owners/{ownerId}/assets/{assetId}/windows/{windowId}`

DELETE `/assets/owners/{ownerId}/assets/{assetId}/windows/{windowId}`

GET `/assets/owners/{ownerId}/audit`

GET `/assets/owners/{ownerId}/calendar.ics`

GET `/assets/owners/{ownerId}/export`

POST `/assets/owners/{ownerId}/import`

GET `/assets/owners/{ownerId}/members`

POST `/assets/owners/{ownerId}/members`

DELETE `/assets/owners/{ownerId}/members/{memberId}`

GET `/assets/owners/{ownerId}/report`

GET `/assets/owners/{ownerId}/reservations`

POST `/assets/owners/{ownerId}/reservations/{reservationId}/cancel`

PATCH `/assets/owners/{ownerId}/reservations/{reservationId}/modify`