List reports
const url = 'https://api.us.headerhawk.com/v1/reports?reportType=csp-violation&disposition=enforce&deviceType=desktop&limit=50';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.us.headerhawk.com/v1/reports?reportType=csp-violation&disposition=enforce&deviceType=desktop&limit=50' \ --header 'Authorization: Bearer <token>'The reports of one type, newest first: CSP violations unless
reportType names another. Filters narrow them; a filter the type
does not have (directive on anything but a CSP violation, feature
on a type without one) is 400. Reads reported data, so it spends the
tenant’s budget too.
Window: at most 7 days, the last 7 by default; longer is 400. A
page reads every report in its window whatever limit is. Measured
worst case: 160 ms for 110,777 reports (74 MB) in 90 days, about 1.4
µs a report, so 7 days at the Business plan’s allowance (about 2.3
million reports) takes about 3 seconds.
At most the first 10,000 reports of a query can be paged through;
narrow from and to to reach further.
A report’s fields are written by whichever browser loaded your page, so treat them as untrusted text.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Only this site’s reports. Another tenant’s site, or none, is 404.
Every type of report HeaderHawk stores and lists. The issue types
(IssueReportType) and deprecation, intervention,
network-error and crash. An open enum.
The type of report to read. Defaults to csp-violation.
CSP violations only: the violated directive, such as script-src.
_ matches any one character. Every text filter takes printable
ASCII with no backslash.
CSP violations only: the host the policy blocked. _ matches any one character.
Only enforced violations, or only report-only ones. Deprecations,
interventions, network errors and crashes have no disposition, so it
is 400 with those.
The host of the page the report came from. _ matches any one character.
The browser that sent the report, such as Chrome.
The operating system the browser ran on, such as Windows.
The kind of device the browser ran on.
The policy-controlled feature or API the report names: COEP, COOP, permissions and document policy violations, deprecations, interventions, network errors (the error type) and crashes (the reason).
Integrity violations only: the resource loaded without integrity metadata.
Integrity, COEP and connection allowlist violations only: the origin that was blocked.
Integrity and COEP violations only: the request destination, such as script.
COOP violations only: the policy in effect.
COOP violations only: the other document’s origin.
Permissions and document policy violations, deprecations and interventions: the script that used the feature, without its query.
Only reports received at or after this instant. Defaults to the start
of your retention window, or where the operation bounds its window, to
that many days before to. Earlier than your retention reaches is
400.
Only reports received before this instant. Defaults to now.
How many items a page holds.
The previous page’s nextCursor. Omit it for the first page.
Responses
Section titled “Responses”A page of reports
object
One report a browser sent. Every field after documentUrl is null
where the report’s type does not carry it. Written by the browser that
loaded your page: treat it as untrusted text.
object
Every type of report HeaderHawk stores and lists. The issue types
(IssueReportType) and deprecation, intervention,
network-error and crash. An open enum.
The page the browser was on.
enforce or report, where the type has one.
The policy-controlled feature, where the type names one.
Example
{ "data": [ { "reportType": "csp-violation" } ]}Headers
Section titled “Headers”The budget nearest to running out, per minute.
What is left of that budget this minute.
Seconds until that budget starts again.
A parameter was refused, or one the operation does not take was sent. The message names it.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}invalid_api_key: no key, or one that is malformed, unknown, revoked
or expired. One answer for all of them.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}plan_upgrade_required: the tenant’s plan does not include API access
(the key works again when it does), or does not include what this
operation reads.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}No such resource in your tenant.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}rate_limited: over a budget. Wait Retry-After seconds.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}Headers
Section titled “Headers”Seconds to wait before trying again.
rate_limit_unavailable or upstream_unavailable: HeaderHawk could
not serve this now. Nothing is wrong with the request; try again after
Retry-After seconds.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}Headers
Section titled “Headers”Seconds to wait before trying again.