Endpoint Reference

336 operations across 25 groups. Every path below is relative to https://app.vitalsentinel.com/api/public/v1.

This page is a map. The OpenAPI document is the contract, and it carries the request and response schemas, the query parameters, and the per-operation notes that are too long to fit in a table.

Read the conventions first. Pagination, time ranges, and idempotency apply across the whole surface and are not repeated per endpoint.

MetaCopy Anchor Link

No scope required. Both cost 0 credits.

CrawlerCopy Anchor Link

No scope required. Unauthenticated. Costs 0 credits.

Use it to keep your firewall allowlist up to date. See Monitoring IPs.

Workspaces and domainsCopy Anchor Link

Read-only. Creating or editing a workspace or a domain is a dashboard-only operation.

/workspaces and /domains return the page envelope but always as a single page today, and both cost 0 credits.

Domain overview and healthCopy Anchor Link

The two cross-module summaries. Start here rather than fanning out across every module.

/overview covers eleven modules, including Page Monitoring, Site Health Monitoring and Sitemap Monitoring. /health covers nine modules, including Site Health Monitoring. A module block is null when the module is not set up for the domain. null does not mean healthy. Both use a fixed 28-day window that is not configurable. The differences that decide which you want:

/health is the one to reach for during an incident. Pass freshness=live to bypass the cache and recompute every module now. It is slower, and cache_age_seconds comes back as 0 so you know you got a fresh answer.

On the default freshness=cached, check meta.cache_age_seconds before trusting uptime.is_up. A snapshot up to an hour old is fine for a dashboard and wrong for "is the site up right now".

/overview has no freshness lever at all, so do not use it for a time-sensitive question. Use /health?freshness=live, or /uptime/status, which is never cached.

URL OverviewCopy Anchor Link

The response has one section for each module: crawl data, Search Console, URL inspection, server logs, sitemap, robots.txt, Web Analytics, RUM, CrUX, Synthetic Monitoring, uptime and open alerts. Each section shows the latest state, not the history.

Each section has a status. not_in_scope means that the credential has no scope for that module. not_connected means that the module is not available for the domain. timeout means that the section was too slow, and the other sections still come back.

A cached answer costs 0. A credential that holds only read:overview pays 0 and gets only the url section.

CreditsCopy Anchor Link

All three cost 0 credits. /credits and /credits/log take an optional workspace_id; /credits/workspaces takes no parameters, because it already covers every workspace the credential can reach. A request is charged to the workspace whose data it read, so a connection covering several workspaces has a separate balance and a separate log for each. Omit the parameter for the connection's default workspace, which is the only one for an API key.

Workspaces do not share a billing cycle, so the balances /credits/workspaces returns each carry their own cycle_start and cycle_end. Adding their used figures together blends different date ranges into a number that describes no real cycle.

See API credits.

UptimeCopy Anchor Link

Scope: read:uptime. There is no write:uptime; uptime configuration is dashboard-only.

SSLCopy Anchor Link

Scope: read:ssl.

CrUXCopy Anchor Link

Scopes: read:crux, write:crux.

There is no way to trigger a CrUX refresh through the API. Collection draws from a shared platform-wide key pool, so a scripted refresh loop would degrade collection for every other customer.

Synthetic MonitoringCopy Anchor Link

Scopes: read:synthetic, write:synthetic. There is no run:synthetic: a scripted "run it now" against the schedule is an unbounded test bill for data that was coming anyway.

RUMCopy Anchor Link

Scope: read:rum. Read-only, and redacted more strictly than the dashboard.

/workspaces/{workspace_id}/rum/has-data is the one workspace-scoped route in this group, so it takes a workspace_id rather than a domain_id. It reports every domain in the workspace in one call, which is how to find out which of your sites are reporting RUM at all without asking domain by domain.

/rum/vitals/ttfb/subparts/timeline gained a sixth field, avg_waiting_time_ms. It is the span from navigation start to the DNS lookup - redirects, the previous page's unload, service-worker start-up and the cache lookup - and it is the phase the breakdown never measured. With it, avg_waiting_time_ms + avg_dns_time_ms + avg_connection_time_ms + avg_request_time_ms equals TTFB exactly. The TLS and response fields are context, not summands: TLS is already inside connection setup, and the response is the body download that begins after the first byte.

The field is nullable, and null means "not measured", never zero - a real reading of zero is possible, so the two cannot share a value. Do not coalesce it to 0, which turns an unmeasured phase into a published reading of zero.

The RUM days parameters cap at 496, which covers the full 16-month window RUM is kept for. A larger value returns 422 rather than an empty series.

Web AnalyticsCopy Anchor Link

Scopes: read:analytics, write:analytics, run:analytics.

Google Search ConsoleCopy Anchor Link

Scopes: read:gsc, write:gsc, run:gsc.

Search Console data hangs off the domain its property is linked to. Connecting or disconnecting a Google account is a dashboard-only operation.

Indexing MonitoringCopy Anchor Link

Scopes: read:indexing, write:indexing.

Robots.txt MonitoringCopy Anchor Link

Scopes: read:robots, write:robots. There is no run:robots; robots.txt is fetched on a schedule.

write:robots edits VitalSentinel's own annotations on a change, and triggers the sitemap-conflict recompute. It does not, and cannot, edit the robots.txt file on your site.

The recompute re-diffs the sitemap URLs VitalSentinel has already stored against the current robots.txt. It returns straight away and does the work in the background, so poll /robots/sitemap-conflicts/summary for the result. It does not fetch a fresh sitemap, so it clears the staleness caused by the check lagging behind a stored sitemap, but not the staleness caused by an old sitemap check. Sitemap Monitoring reads the sitemaps again every 24 hours, and that clears it.

Sitemap MonitoringCopy Anchor Link

Scope: read:sitemap. Read-only. VitalSentinel checks the sitemaps of each domain automatically every 24 hours. See Sitemap Monitoring.

Some fields need a second scope. Search Console figures, such as clicks on a removed URL, need read:gsc. Google indexing figures on a sitemap file need read:indexing. Without the second scope, these fields are null.

To find sitemap URLs blocked by robots.txt, either read the stored result at /robots/sitemap-conflicts, refreshing it first with POST /robots/sitemap-conflicts/recompute if it is stale, or export the full URL list here plus the latest robots.txt and compute the intersection yourself.

Site Health MonitoringCopy Anchor Link

Scopes: read:site_health, write:site_health. There is no run:site_health, because your plan sets how often pages are checked. Every write: operation needs the owner or admin role. See Site Health Monitoring.

Page MonitoringCopy Anchor Link

Scopes: read:pages, write:pages, run:pages. Every write: and run: operation needs the owner or admin role. See Page Monitoring.

A check started through the API uses the same hourly allowance as the Check now button in the dashboard. When the allowance is used, the API refuses the check with a rate-limit error. A retry with the same Idempotency-Key returns the same check and costs 0.

Stored page versionsCopy Anchor Link

Scope: read:pages or read:site_health. Site Health Monitoring and Page Monitoring share the stored versions of a page, so either scope reads them. A 403 lists both scopes and shows that one of them is enough.

The stored HTML comes from your site. The API returns it as text, never as a web page.

Server Log MonitoringCopy Anchor Link

Scope: read:logs. Read-only: there is no write:logs or run:logs, so the API cannot connect a log source or start a collection run.

Every route costs 5 credits on the heavy-query rate-limit bucket, except /logs/sources and /logs/exclusions, which cost 1. The API never returns a visitor IP address: unverified and spoofed traffic is grouped per network (ASN). See Server Log Monitoring for what each report means.

The cross-module routes return a source-coverage block, so a figure that a missing source (Search Console, Web Analytics, RUM or a sitemap) cannot establish comes back as unknown rather than zero.

AlertsCopy Anchor Link

Scopes: read:alerts, write:alerts. Members can create and edit alert rules, because a rule belongs to whoever created it.

Alert rules also cover Page Monitoring, Site Health Monitoring and Sitemap Monitoring. See Alert types.

The account-wide /alerts/rules and /alerts/history answer "what do I have set up" and "what has fired lately" across every workspace the credential can reach, without looping over /domains first. Every row names its own domain and workspace, so nothing has to be correlated against a second call. Both cost 0 credits, because a call that reads every accessible workspace has no single workspace to charge. Narrowing one with workspace_id or domain_id does not change that, since those are query filters rather than part of the path.

Read /alerts/metrics before building a rule. It is free and it is what tells you which metric and comparison combinations are valid.

There is no endpoint to test-fire a rule. The dashboard does not expose one either.

NotificationsCopy Anchor Link

Scopes: read:notifications, write:notifications. Scoped to the calling user, not to the workspace. Members keep write access here, because these are personal preferences.

Because they are user-scoped rather than workspace-scoped, every route in this group costs 0 credits. The one exception is GET /notifications/{notification_id}/trend, which recomputes a series from live data and costs 1.

Fired alerts arrive as notifications carrying the alert rule and alert history identifiers, so this is where you watch for an alert firing.

ReportsCopy Anchor Link

Scopes: read:reports, write:reports, run:reports.

PDF generation is asynchronous. POST .../generate returns a job identifier; poll /reports/jobs/{job_id} until it completes, then download. Polling is priced as an ordinary read, so watching a report never costs more than starting one.

If you want the numbers rather than a PDF, use POST /reports/data/{template_id}. It returns the same content as JSON, needs only read:reports, and costs a read rather than 25 credits.

OAuthCopy Anchor Link

The authorization server. See Authentication for the full flow.

Two discovery documents sit at the site root rather than under the API prefix:

GET https://app.vitalsentinel.com/.well-known/oauth-authorization-server
GET https://app.vitalsentinel.com/.well-known/oauth-protected-resource