Each entry is a version of the API's OpenAPI document, which the API reference is built from. Additions can arrive at any time. A change that could break your software is announced here before it takes effect, as section 8 of the API Terms describes.
1.9.0 -
- A new webhook event type,
report.ready, says that the scan report of a completed scan is ready. Itsdatanames the site and the scan, gives the report'sschema_version,content_hash,built_atandpdf.status, and carries inlinksthe addresses of the JSON report and the PDF, which need an API key withreports:read. An endpoint can subscribe to it now. Scan reports are not switched on yet, so noreport.readyevent is sent until they are announced here. You do not have to change anything. - The description of
GET /v1/sites/{siteKey}/scansnow says that old scans are deleted every day, not once a week, and that a deleted scan's report goes with it. You do not have to change anything.
1.8.0 -
- A new operation,
GET /v1/sites/{siteKey}/scans/{scanId}/report/pdf, returns the scan report as a PDF file, printed from the same document as the JSON report, with the permissionreports:read. A PDF that is still being made answers 409report_not_readywith aRetry-Afterheader, and when 10 of your organisation's PDFs are already waiting to be made, the answer is 429queue_fullwithRetry-After. Scan reports are not switched on yet, so the operation answers 404not_founduntil they are announced here. You do not have to change anything.
1.7.1 -
- The description of
GET /v1/sites/{siteKey}/scans/{scanId}/reportnow says how many report builds your organisation's requests start: up to 20 in each window of 60 seconds, and one more when two of your requests arrive at the same moment. Scan reports are not switched on yet. You do not have to change anything.
1.7.0 -
- Two new operations for scan reports:
GET /v1/sites/{siteKey}/scans/{scanId}/reportreturns the scan report of a scan that ran to its end, with the new permissionreports:read, andGET /v1/schemas/scan-report-1.jsonreturns the report's JSON Schema without an API key. A report that is not ready yet answers 409 with the new error codereport_not_readyand aRetry-Afterheader. API keys created before this change do not havereports:read: create a new key to get it. Scan reports are not switched on yet, so both operations answer 404not_founduntil they are announced here. You do not have to change anything.
1.6.0 -
GET /v1/sites/{siteKey}/scans/{scanId}has a new member,before_consent: what the scan's first pages set and loaded when the scanner loaded them again as a first-time visitor who has not made a choice in any cookie banner, as astatus(not_checked,partialorchecked) and counts of the pages, cookies, storage keys and hosts. This check is not switched on yet, so every scan readsnot_checkedwith no page planned until then. The scans list and the answer to starting a scan do not change. You do not have to change anything.
1.5.0 -
- Webhooks are switched on. Webhook endpoints (
GETandPOST /v1/webhook-endpoints,GET,PATCHandDELETE /v1/webhook-endpoints/{endpointId},POST /v1/webhook-endpoints/{endpointId}/rotate-secretandPOST /v1/webhook-endpoints/{endpointId}/test) and events (GET /v1/eventsandGET /v1/events/{eventId}) now answer, with the permissionswebhooks:readandwebhooks:write, on plans that include the API. To receive and verify events, read Receive webhooks in the Help Centre. You do not have to change anything. - The description of
DELETE /v1/webhook-endpoints/{endpointId}is corrected: the answer does not wait for what is already on its way, so a message sent before the delete can still reach the endpoint after the answer. Nothing else is sent to it.
1.4.0 -
POST /v1/webhook-endpointsand aPATCH /v1/webhook-endpoints/{endpointId}that changesurlcan answer 429concurrency_limitedwith aRetry-Afterheader while another address check or test event of your organisation is running, or while Kukie.io is checking as many addresses and sending as many test events as it allows at once, and 503service_unavailablewhen the check can't run because of a fault in Kukie.io. Neither answer writes anything: wait the seconds inRetry-After, then send the request again. APATCHthat sends theurlthe endpoint already has does not check it again.POST /v1/webhook-endpoints/{endpointId}/testalso answers 429 while an address check of your organisation is running. Webhooks are not switched on yet, so these operations still answer 404not_found.
1.3.1 -
DELETE /v1/webhook-endpoints/{endpointId}no longer answers 403plan_upgrade_required: you can delete a webhook endpoint when your plan no longer includes the API. Every other webhook operation still needs the plan. Webhooks are not switched on yet, so this operation still answers 404not_found. You do not have to change anything.
1.3.0 -
- New, and not switched on yet: webhook endpoints (
GETandPOST /v1/webhook-endpoints,GET,PATCHandDELETE /v1/webhook-endpoints/{endpointId},POST /v1/webhook-endpoints/{endpointId}/rotate-secretandPOST /v1/webhook-endpoints/{endpointId}/test) and events (GET /v1/eventsandGET /v1/events/{eventId}), which need the permissionswebhooks:readandwebhooks:write. Until webhooks are announced here, these operations answer 404not_found. You do not have to change anything.
1.2.1 -
- Descriptions corrected, with no change to any operation or member, or to the status or
codeof any answer. Deleting a site names the security email that the owner and every admin get. Creating and deleting a site, and a copy of settings, say how they count toward the budget for banner rebuilds, which now names its limit for a minute. The introduction says when a stored idempotent answer is deleted, when a retry runs again, and that an operation on something with noetagyet must be sent withoutIf-Match. - The
errorsmember of an error is also filled with a 409conflictabout a site'sdomainorexternal_id, as the API already answered.existing_site_idcomes with that conflict when your API key can read the other site. - The usual
detailof 412precondition_failedand of 503service_unavailablegives better advice. Decide bycode, never bydetail.
1.2.0 -
GET /v1/usagecan answer 503service_unavailablewith aRetry-Afterheader when its figures take too long to compute. Wait that long, then ask for a shorter window.
1.1.1 -
- The
messageof a scan with failed pages gives the number of pages that failed, without their addresses. The addresses stay in the scan'sfailed_pages.
1.1.0 -
- A copy of settings (
copy_settings_fromwhen you create a site, andPOST /v1/sites/{siteKey}/copy-settings) carries the banner settings, the texts and the region rules, and a copy to other sites also, on request, the cookies added by hand and your own services. It never copies the consent logging switch or the scan frequency, and it copies the accessibility widget only when the API key also has theaccessibility:writepermission. A site left with a widget that differs from the source's gets the warningaccessibility_widget_not_copied. GET /v1/accountcounts only the sites an API key reaches when the key is limited to chosen sites, and itscan_create_siteisfalsefor such a key.
1.0.0 -
- The first version of the API: sites, banner settings and texts, region rules, cookies and categories, the accessibility widget, cookie scans, consent records and statistics, the account and API usage.
