Get one scan

GET

/v1/sites/{siteId}/pages/{pageId}/scans/{scanId}

const url = 'https://api.us.headerhawk.com/v1/sites/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/pages/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/scans/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
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/sites/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/pages/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/scans/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

One scheduled scan with its full graded result and, for a payment page on a plan with script authorization, the scripts its HTML named.

Authorizations

apiKey

Parameters

Path Parameters

siteId

required

string format: uuid

The site’s id.

pageId

required

string format: uuid

The monitored page’s id.

scanId

required

string format: uuid

The scan’s id.

Responses

200

The scan

application/json

object

data

required

object

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

result

required

The graded result, as HeaderHawk’s free header scanner gives it: grade, score, headline, the finding for each header and what to do next. Null for a failed scan. Its shape follows the scanner’s and may gain fields.

object

key

additional properties

any

scripts

required

The page’s script tags with a src, in document order, each fetched and hashed. Only a payment page on a plan with script authorization has its scripts fetched: null for every other scan, and for a failed one.

Array<object>

nullable

One script tag with a src the scan found, and what fetching it gave.

object

src

required

The src attribute as written.

string

url

required

Resolved against the page, query kept; null when it does not resolve.

string

nullable

identityUrl

required

The script inventory’s identity for it, query and fragment dropped.

string

nullable

sameOrigin

required

boolean

integrity

required

The tag’s integrity attribute.

string

nullable

outcome

required

hashed: fetched and hashed. failed: fetched, and what came back was not a script that could be hashed. refused: not fetched, because its URL or a redirect led where scans do not go, or it has no URL (data:). skipped: not fetched, past the per-page limit or because the scan ran out of time. An open enum.

string

Allowed values: hashed failed refused skipped

hash

required

sha256-<base64> of the bytes served; null unless outcome is hashed.

string

nullable

size

required

Bytes hashed.

integer

nullable

problem

required

Why there is no hash; null when there is one.

object

reason

required

A string, so a new reason does not break a client.

string

message

required

string

cors

required

Whether the page’s own origin could integrity-check it, asked with that origin; null unless it was fetched.

object

verdict

required

An open enum.

string

Allowed values: readable credentialed not_readable

allowOrigin

required

string

nullable

allowCredentials

required

boolean

redirected

required

boolean

failingHop

required

object

url

required

string

statusCode

required

integer

originSent

required

string

allowOrigin

required

string

nullable

message

required

string

Example

{
  "data": {
    "status": "complete",
    "changes": {
      "headers": [
        {
          "header": "content-security-policy",
          "change": "added"
        }
      ]
    },
    "scripts": [
      {
        "outcome": "hashed",
        "cors": {
          "verdict": "readable"
        }
      }
    ]
  }
}

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

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

application/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

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

application/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

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.

application/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

No such resource in your tenant.

application/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

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

application/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

Retry-After

integer

Seconds to wait before trying again.