Cybersecurity glossary
What is the Reporting API?
Learn what the Reporting API is, how browsers queue CSP, COOP, and deprecation reports, how Reporting-Endpoints configures collectors, and how to build privacy-safe violation monitoring.
Definition
The Reporting API is a browser mechanism that lets websites register collector URLs and receive structured reports about policy violations, deprecations, and other browser-generated events, typically delivered via asynchronous POST requests defined in Reporting-Endpoints.
Why the Reporting API matters
Security headers only help when teams know they fired. A mis-typed CSP directive, a broken third-party script, or a COOP mismatch can fail silently for users while quietly weakening defenses.
The Reporting API gives browsers a standard way to ship structured telemetry to endpoints you control. Instead of guessing from broken pages, engineers receive machine-readable events they can alert on, trend, and fix before enforcement breaks production.
How the Reporting API works
Origin registers collectors
Reporting-Endpoints maps report type names to HTTPS collector URLs on your infrastructure.
Policies reference report types
CSP, COOP, and other features name a collector group defined in Reporting-Endpoints.
Browser detects a reportable event
A violation, deprecation, or intervention triggers report generation in the client.
Reports are queued
The browser batches and rate-limits delivery to avoid overwhelming collectors.
Collector ingests JSON
Your endpoint receives POST bodies you parse, store, and route to monitoring tools.
Common report types
csp-violation
Blocked scripts, styles, or connections that violate Content Security Policy rules.
coop
Cross-Origin-Opener-Policy issues when browsing context groups do not match expectations.
deprecation
Warnings that a site uses APIs or features scheduled for removal.
intervention
Browser mitigations applied to protect users, such as heavy ad or autoplay limits.
network-error
Optional Network Error Logging reports for failed fetches when configured.
crash
Some platforms support crash reporting integrations through reporting infrastructure.
Collector design considerations
| Concern | Recommended practice | Why |
|---|---|---|
| Authentication | Use unguessable collector paths plus network ACLs or tokens | Public endpoints can be spammed or probed |
| Privacy | Strip or hash query strings; minimize PII in stored payloads | Reports include document URLs and blocked URIs |
| Volume | Sample, deduplicate, and rate-limit ingestion | Noisy policies can generate thousands of near-duplicate events |
| Retention | Short TTL with aggregation into metrics | Raw reports are verbose and age quickly after fixes |
Security checklist
- Serve Reporting-Endpoints over HTTPS on origins that emit security policies.
- Register separate collector groups for staging and production to avoid alert noise.
- Validate Content-Type and JSON schema; reject malformed or oversized POST bodies.
- Monitor collector availability—silent endpoints mean blind enforcement rollouts.
- Start CSP in Report-Only mode and confirm reports arrive before switching to enforce.
- Restrict collector access at the edge; do not expose raw report databases publicly.
- Alert on spikes that may indicate active injection attempts, not only steady-state noise.
- Document which report types each environment enables so COOP and CSP teams share one pipeline.
Limits and pitfalls
Reporting is best-effort. Browsers may drop reports under memory pressure, offline conditions, or aggressive rate limiting. Do not treat the Reporting API as an audit log with guaranteed delivery.
Legacy Report-To headers and CSP report-uri still appear in older docs and stacks. Modern deployments should prefer Reporting-Endpoints, but mixed configurations during migration can duplicate or lose events.
Collectors that echo report contents into admin UIs without sanitization can become XSS sinks. Treat inbound report JSON as untrusted input.
The practical takeaway
The Reporting API connects browser-detected policy failures to infrastructure you operate. Paired with Reporting-Endpoints, it turns CSP and related headers from silent guards into observable signals.
Register collectors early, harden ingestion, and use reports to tune policies before enforcement breaks real users—not as a substitute for secure coding and testing.
Related security terms
Reporting-Endpoints
The HTTP header that maps report types to collector URLs for the Reporting API.
Content Security Policy (CSP)
A major source of violation reports sent through reporting collectors.
Cross-Origin-Opener-Policy (COOP)
May emit reports when cross-origin isolation expectations are violated.
Cross-Origin-Embedder-Policy (COEP)
Related isolation policy that can surface embedding issues worth monitoring.
Frequently asked questions
What is the Reporting API in simple terms?
It is how a website tells the browser where to send automatic problem reports—like Content Security Policy violations—so teams can monitor issues without waiting for users to complain.
How is the Reporting API different from CSP report-uri?
Legacy CSP used report-uri (and report-to) per policy. The modern Reporting-Endpoints header centralizes collector URLs for multiple report types, including CSP, in one configuration.
What kinds of reports can browsers send?
Common types include CSP violations, Cross-Origin-Opener-Policy reports, deprecation warnings, intervention reports, and network error logging when enabled.
Are reporting payloads sensitive?
They can include page URLs, blocked resource URLs, line numbers, and sometimes script samples. Treat collectors as security-sensitive infrastructure with access controls and retention limits.
Do reports block page loads?
No. Reporting is asynchronous. Browsers queue reports and deliver them in the background, often with batching and rate limits.
Can I use the Reporting API without CSP?
Yes. Reporting-Endpoints can register collectors for several report types. CSP is one consumer, not the only one.
References
Explore authoritative guidance and frameworks related to reporting api.
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.