Information
- OpenAPI version:
3.0.3
Overview
HeaderHawk API 1.0.0
Section titled “HeaderHawk API 1.0.0”Read your HeaderHawk data from your own code: your sites, the issues browsers have reported on them and the reports behind each issue, every report of each type with its counts, the network errors and crashes browsers reported, the deprecated APIs your pages use, the pages you monitor with their scans and the CSP policies they served, the alerts HeaderHawk sent, your script inventory with its decisions, and each site’s PCI DSS 4.0 readiness.
Authentication. Every request carries one of your tenant’s API keys as
a bearer token: Authorization: Bearer hh_live_…. An owner or admin issues
keys on the Professional plan and above, under Settings › API keys, and a
key is shown once. A key reads what a viewer reads and changes nothing.
A key that is missing, malformed, unknown, revoked or expired is refused
with 401 invalid_api_key, one message for all of them; a key whose
tenant’s plan no longer includes API access is refused with
403 plan_upgrade_required, and works again when the plan does. Revoking
a key takes effect within 60 seconds.
Browsers. The API sends no CORS headers, on purpose: a key in a web page is a key given to every visitor to that page. Call it from a server.
Stability. Everything is under /v1. Inside v1, fields are only
ever added to a response: none is removed, renamed, retyped or made
nullable, and no request parameter becomes required. Ignore a field you do
not know. Every enum is open: a new value is announced in the changelog at
least 14 days before it ships, so treat a value you do not know as
other. An operation marked x-stability: beta may change with a
changelog entry and no notice period; every operation is beta until a
customer outside HeaderHawk has used it.
Errors. Every error, whoever answered it, has one shape:
{"error": {"code": "…", "message": "…", "requestId": "…"}}. Branch on
code, never on message, and quote requestId when you write to us.
Pagination. A list takes limit (1 to 200, default 50) and answers
{"data": […], "nextCursor": "…"}. Pass nextCursor back as cursor for
the next page, with the same other parameters; it is null on the last
page. A cursor is opaque and belongs to the query that produced it.
Rate limits. Each key may make 600 requests a minute. The operations
that read reported data (each says so in its description) also share a
budget
of 60 a minute across the whole tenant, whichever key or assistant spends
it. A request that reaches a budget, which is every one with a valid key
and valid parameters, gets RateLimit-Limit, RateLimit-Remaining and
RateLimit-Reset (seconds) for whichever budget is nearest to running
out; a refusal before that (a bad key, a bad parameter) has none, and
spends nothing. Over a budget is 429 rate_limited with Retry-After; a
503 with Retry-After means try again then, and is never a sign you
did anything wrong.
Time. Timestamps are ISO 8601 in UTC. from and to bound a list to
the reports received in that window, and default to your plan’s whole
retention window. A from earlier than the start of the UTC day your
retention reaches back to is 400, not an empty page: HeaderHawk has
deleted those reports, and an empty answer would say there were none.
The issues, the reports and everything that counts or groups them read a
bounded window instead. The issue lists and every /v1/reports operation
default to the 7 days before to, so a count asked with a list’s
parameters counts that list; a page of reports reads at most 7 days, and
the issue lists and the count, groups, histogram and types at most 31.
Network errors, crashes, browser changes, CSP policies and scripts
default to 31 days and read at most 31. A longer window is 400; ask for consecutive
ones.
Authentication
Section titled “Authentication”apiKey
Section titled “apiKey”One of your tenant’s API keys, hh_live_ and 49 more characters.
Security scheme type: http