Skip to content
HeaderHawk

List a monitored page's scans

GET
/v1/sites/{siteId}/pages/{pageId}/scans
curl --request GET \
  --url 'https://api.us.headerhawk.com/v1/sites/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/pages/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/scans?limit=50' \
  --header 'Authorization: Bearer <token>'

A monitored page’s scheduled scans, newest first, with the page’s latest complete scan beside them: its current state, however many failed scans followed it. A scan here carries its headers and what changed since the last one; GET a single scan for its full graded result.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
siteId
required
string format: uuid

The site’s id.

pageId
required
string format: uuid

The monitored page’s id.

Query Parameters

Section titled “Query Parameters”
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 scans

Media typeapplication/json
object
data
required
Array<object>
object
id
required
string format: uuid
pageId
required
string format: uuid
scannedAt
required
string format: date-time
scanUrl
required

The URL fetched, as the page named it when it was scanned.

string
status
required

complete, or failed with a failureReason. An open enum.

string
Allowed values: complete failed
failureReason
required

As on LatestPageScan.

string
nullable
failureMessage
required
string
nullable
consecutiveFailures
required
integer
rubricVersion
required

The scan rubric’s version: a grade is compared only with one given under the same rubric.

integer
grade
required

The letter grade HeaderHawk’s scan rubric gave the page’s headers: A+, A, B, C, D or F. Null for a failed scan.

string
nullable
score
required

The score behind the grade, 0 to 100; null for a failed scan.

integer
nullable
finalUrl
required

Where the fetch ended after redirects.

string
nullable
statusCode
required
integer
nullable
headers
required

The watched security headers in comparable form, each null when the page did not send it; null for a failed scan. A policy’s directives are sorted with every nonce replaced by 'nonce-*'; other values are lowercased with whitespace collapsed. A header sent more than once is its lines, sorted, joined with a newline.

object
content-security-policy
required
string
nullable
content-security-policy-report-only
required
string
nullable
strict-transport-security
required
string
nullable
x-frame-options
required
string
nullable
x-content-type-options
required
string
nullable
referrer-policy
required
string
nullable
permissions-policy
required
string
nullable
changes
required

What differs from the page’s last complete scan.

object
headers
required
Array<object>

One watched header that differs from the last complete scan.

object
header
required

The header’s name, lowercase. An open enum.

string
Allowed values: content-security-policy content-security-policy-report-only strict-transport-security x-frame-options x-content-type-options referrer-policy permissions-policy
change
required

An open enum.

string
Allowed values: added removed changed
before
required
string
nullable
after
required
string
nullable
gradeDroppedFrom
required

The last complete scan’s grade, when this one is lower under the same rubric; otherwise null.

string
nullable
rebaselined
required

The rubric changed since the last complete scan, so the grade was not compared.

boolean
latestComplete

The page’s latest complete scan, its current state, however many failed scans followed it. Absent until it has had one.

object
id
required
string format: uuid
pageId
required
string format: uuid
scannedAt
required
string format: date-time
scanUrl
required

The URL fetched, as the page named it when it was scanned.

string
status
required

complete, or failed with a failureReason. An open enum.

string
Allowed values: complete failed
failureReason
required

As on LatestPageScan.

string
nullable
failureMessage
required
string
nullable
consecutiveFailures
required
integer
rubricVersion
required

The scan rubric’s version: a grade is compared only with one given under the same rubric.

integer
grade
required

The letter grade HeaderHawk’s scan rubric gave the page’s headers: A+, A, B, C, D or F. Null for a failed scan.

string
nullable
score
required

The score behind the grade, 0 to 100; null for a failed scan.

integer
nullable
finalUrl
required

Where the fetch ended after redirects.

string
nullable
statusCode
required
integer
nullable
headers
required

The watched security headers in comparable form, each null when the page did not send it; null for a failed scan. A policy’s directives are sorted with every nonce replaced by 'nonce-*'; other values are lowercased with whitespace collapsed. A header sent more than once is its lines, sorted, joined with a newline.

object
content-security-policy
required
string
nullable
content-security-policy-report-only
required
string
nullable
strict-transport-security
required
string
nullable
x-frame-options
required
string
nullable
x-content-type-options
required
string
nullable
referrer-policy
required
string
nullable
permissions-policy
required
string
nullable
changes
required

What differs from the page’s last complete scan.

object
headers
required
Array<object>

One watched header that differs from the last complete scan.

object
header
required

The header’s name, lowercase. An open enum.

string
Allowed values: content-security-policy content-security-policy-report-only strict-transport-security x-frame-options x-content-type-options referrer-policy permissions-policy
change
required

An open enum.

string
Allowed values: added removed changed
before
required
string
nullable
after
required
string
nullable
gradeDroppedFrom
required

The last complete scan’s grade, when this one is lower under the same rubric; otherwise null.

string
nullable
rebaselined
required

The rubric changed since the last complete scan, so the grade was not compared.

boolean
nextCursor
required
string
nullable
Example
{
  "data": [
    {
      "status": "complete",
      "changes": {
        "headers": [
          {
            "header": "content-security-policy",
            "change": "added"
          }
        ]
      }
    }
  ],
  "latestComplete": {
    "status": "complete",
    "changes": {
      "headers": [
        {
          "header": "content-security-policy",
          "change": "added"
        }
      ]
    }
  }
}

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.