Wiki · Concept · Last reviewed June 25, 2026

Reporting API

The Reporting API is browser infrastructure for turning security, policy, and runtime problems into structured reports delivered to named endpoints.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser security, telemetry, policy reports, agents, governance

Definition

The Reporting API is a W3C browser framework for associating named reporting endpoints with an origin and sending feature-specific reports to those endpoints. The W3C Working Draft describes it as generic reporting infrastructure that other platform features can use. MDN frames it similarly: a consistent mechanism for reports from features such as Content Security Policy, Permissions Policy, and browser deprecation reporting.

The key idea is not that the website logs itself. The browser generates reports about events it can observe: a policy violation, a deprecated API, an intervention, a crash, or another standardized condition. The site declares where reports may go; the user agent decides what is generated and whether delivery happens.

How It Works

A site configures endpoints with the Reporting-Endpoints response header. The W3C draft defines the header as a Dictionary Structured Field in which each dictionary entry names an endpoint URL. MDN's header reference describes the same mapping and notes that non-secure endpoint URLs are ignored. A policy header can then refer to an endpoint name, for example by using a CSP report-to directive.

Reports are serialized as application/reports+json. The W3C draft defines common report fields such as type, URL, user agent, destination, timestamp, attempt count, and body. The body is feature-specific: a CSP violation report is not the same as a crash report or a permissions-policy report.

There is also an in-page JavaScript surface, ReportingObserver, for report types that are visible to observers. MDN lists crash, CSP violation, deprecation, intervention, and permissions-policy violation report families, while noting that crash reports cannot be observed in the crashed page. Reports can be sent to server endpoints independently of whether the page continues running.

Agent Context

Reporting matters for browser agents because agents can trigger browser policy edges faster and less visibly than people. An agent may load untrusted content, paste model output into a page builder, automate a payment form, open a cross-origin frame, or run through a web app path that the developers rarely test. CSP, permissions-policy, integrity, deprecation, and intervention reports can show where the browser refused or constrained an action.

That does not make the report stream a perfect agent trace. A browser report is a narrow observation from the user agent's point of view. It does not explain the model instruction, the user's intent, the server-side decision, or the external connector that caused the page to reach that state. Agent systems should connect reporting events to task logs without merging them into one undifferentiated surveillance record.

Governance Use

The governance use is evidence with boundaries. A reporting endpoint can reveal that a policy broke, but the evidence should remain scoped to the policy question. For example, a CSP report can help diagnose an unexpected script source after an agent edited HTML. A permissions-policy report can show that a page tried to use a blocked capability. A deprecation report can show that an automation path depends on a browser feature that is being removed.

For high-risk agent deployments, reporting should be part of a layered audit record. Store the response headers that configured endpoints, the report type, destination name, relevant policy text, URL, frame or worker context where available, browser version, task identifier, and the agent action near the reported event. Do not store raw page contents, full URLs with secrets, access tokens, payment details, or personal data unless the investigation requires them.

Limits

The W3C draft is explicit that delivery is best effort. It says reporting is not a reliable communications channel, network conditions may prevent delivery, and user agents may reject or not deliver reports for any reason. MDN also warns that there is no absolute guarantee of report delivery.

Reporting is also telemetry, not consent. A reporting endpoint can become a detailed event stream about browser behavior, failed requests, blocked capabilities, and site structure. That stream can help maintain security, but it can also become operational surveillance if retained broadly or joined with account profiles. It should be sampled, minimized, access-controlled, and documented.

Minimum Evidence Record

For agent-mediated browsing, preserve the report type, endpoint name, report destination, reporting origin, page or worker URL after stripping secrets, policy header or triggering feature, browser and version, timestamp, task identifier, agent action, and whether the report was observed locally or received server-side. Keep the report body only as long as needed for the policy question.

Source Discipline

Use the W3C Reporting API draft for the generic framework, endpoint header, media type, and delivery guarantees. Use MDN for implementation-oriented report families and header usage. Use Network Error Logging only when the topic is network-failure reporting, because NEL has its own W3C specification and policy header.

Spiralist Reading

Spiralism reads the Reporting API as confession by infrastructure. The browser names the moment when a rule was crossed, a capability was denied, or a feature began to decay. It turns friction into a record.

The danger is turning every refusal into a dossier. Agentic systems need the record, but they also need its humility. A report can say that a boundary fired. It cannot say why a person delegated the action, whether the task was legitimate, or what the system should remember after the incident ends.

Sources

Return to Wiki