Endpoint Reference

217 operations across 19 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.

Meta

No scope required. Both cost 0 credits.

Workspaces and domains

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 health

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

Both cover the same eight modules over 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.

Credits

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.

Uptime

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

SSL

Scope: read:ssl.

CrUX

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 Monitoring

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.

RUM

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.

Web Analytics

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

Google Search Console

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 Monitoring

Scopes: read:indexing, write:indexing.

Robots.txt Monitoring

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 the sitemap scan itself being old. Only a new scan clears that, and starting one is a dashboard-only action.

Sitemap

Scope: read:sitemap. Read-only.

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.

Alerts

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

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.

Notifications

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.

Reports

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.

OAuth

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