Skip to content
HeaderHawk

List issues across your sites

GET
/v1/issues
curl --request GET \
  --url 'https://api.us.headerhawk.com/v1/issues?limit=50' \
  --header 'Authorization: Bearer <token>'

Issues from every site, or from one with siteId, most recently seen first. An issue groups the reports that are about the same thing — for a CSP violation, one directive blocking one host — whichever page sent them. Reads reported data, so it spends the tenant’s budget too.

Window: the last 7 days by default; at most 31, longer is 400. A page reads every report in its window whatever limit is. Measured worst case: 94–101 ms for a page of 200 and 28–33 ms for the count, reading 123,836 reports (32 MB) in 90 days, about 0.8 µs a report.

At most the first 10,000 issues of a query can be paged through; narrow from and to to reach further.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
siteId
string format: uuid

Only this site’s issues.

reportType
string
<= 256 characters /^[a-z-]+(,[a-z-]+)*$/

Only issues of these types, comma-separated. Defaults to every type.

from
string format: date-time

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.

to
string format: date-time

Only reports received before this instant. Defaults to now.

limit
integer
default: 50 >= 1 <= 200

How many items a page holds.

cursor
string
>= 1 characters <= 1024 characters

The previous page’s nextCursor. Omit it for the first page.

Responses

Section titled “Responses”

200

Section titled “200”

A page of issues

Media typeapplication/json
object
data
required
Array<object>
object
id
required
string
siteId
required
string format: uuid
reportType
required

What kind of report an issue groups. An open enum.

string
Allowed values: csp-violation integrity-violation coep coop permissions-policy-violation document-policy-violation connection-allowlist
subject
required

A CSP directive, or what another type’s reports are about.

string
targetHost
required

The host of the blocked resource, or of the source file.

string
directive
required

The CSP directive. Null for every other type.

string
nullable
blockedHost
required

The host the CSP blocked. Null for every other type.

string
nullable
reportCount
required

Reports stored for this issue in the window.

integer
estimatedReportCount
required

reportCount scaled up for the reports a sampling rate below 1 left out; equal to it when nothing was sampled.

integer
sampled
required
boolean
affectedPages
required
integer
browserFamilyCount
required
integer
confidence
required

How sure HeaderHawk is that an issue is real rather than noise, from how many reports and browser families sent it. An open enum.

string
Allowed values: high medium low suppressed
firstSeen
required
string format: date-time
lastSeen
required
string format: date-time
nextCursor
required
string
nullable
Example
{
  "data": [
    {
      "reportType": "csp-violation",
      "confidence": "high"
    }
  ]
}

Headers

Section titled “Headers”
RateLimit-Limit
integer

The budget nearest to running out, per minute.

RateLimit-Remaining
integer

What is left of that budget this minute.

RateLimit-Reset
integer

Seconds until that budget starts again.

400

Section titled “400”

A parameter was refused, or one the operation does not take was sent. The message names it.

Media typeapplication/json
object
error
required
object
code
required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string
Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error
message
required

For people. Branch on code.

string
requestId
required

Quote it when you write to us about this request.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

401

Section titled “401”

invalid_api_key: no key, or one that is malformed, unknown, revoked or expired. One answer for all of them.

Media typeapplication/json
object
error
required
object
code
required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string
Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error
message
required

For people. Branch on code.

string
requestId
required

Quote it when you write to us about this request.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

403

Section titled “403”

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.

Media typeapplication/json
object
error
required
object
code
required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string
Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error
message
required

For people. Branch on code.

string
requestId
required

Quote it when you write to us about this request.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

404

Section titled “404”

No such resource in your tenant.

Media typeapplication/json
object
error
required
object
code
required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string
Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error
message
required

For people. Branch on code.

string
requestId
required

Quote it when you write to us about this request.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

429

Section titled “429”

rate_limited: over a budget. Wait Retry-After seconds.

Media typeapplication/json
object
error
required
object
code
required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string
Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error
message
required

For people. Branch on code.

string
requestId
required

Quote it when you write to us about this request.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before trying again.

503

Section titled “503”

rate_limit_unavailable or upstream_unavailable: HeaderHawk could not serve this now. Nothing is wrong with the request; try again after Retry-After seconds.

Media typeapplication/json
object
error
required
object
code
required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string
Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error
message
required

For people. Branch on code.

string
requestId
required

Quote it when you write to us about this request.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before trying again.