Skip to content
Start free Sign in

Kukie.io API reference

Every operation of the Kukie.io API: what to send, what comes back and which errors to expect.

Overview

The Kukie.io API manages your organisation's sites, banners and cookie scans, and reads consent records, with JSON over HTTPS.

The base URL is https://api.kukie.io. This page is built from the API's OpenAPI document, version 1.9.0, which the API serves at https://api.kukie.io/v1/openapi.json. Postman and Bruno can import it from that URL.

The API is included on the Agency and Unlimited plans. See the pricing page for what each plan includes.

The API Terms apply to your use of the API. The API changelog lists what changed in each version of the document.

New to the API? Start with the guides for developers: a quickstart, API keys and permissions, errors, rate limits, retries, lists and versions.

Authentication

Send an API key of your organisation in the Authorization header: Authorization: Bearer kk_live_.... You create keys on the API keys page of your organisation's settings. Never put a key in a URL: such a request answers 400 credential_in_query, and you should roll that key.

Errors

An error is sent as application/problem+json. Read its code, never title or detail. Every answer of the API carries a Request-Id header, and every error a matching request_id. Quote it when you contact support. The servers in front of the API can answer before it does (a 5xx status of their own, such as 502, when the API cannot be reached, or a 413 for a body far larger than the API accepts): such an answer has neither and is not in this format, so decide by its HTTP status alone.

Lists and cursors

A list answers with data, has_more and next_cursor. Send limit (1 to 100, default 25) and, for the next page, cursor set to next_cursor, with the same API key and the same filters.

Idempotency

On a POST you can send an Idempotency-Key header of up to 255 characters (creating a site needs one). A key counts only for the API key that sent it, and a stored answer is kept until 24 hours after the first request with that key, then deleted within the hour. The same key with the same request replays the stored answer with Idempotent-Replayed: true: its status and body, without the other headers of the first answer, such as Location, ETag and Retry-After. With another request it answers 422 idempotency_key_reuse, and while the first runs, 409 idempotency_in_flight. Only a success of up to 65536 bytes is stored, and only within your organisation's budget of 100,000,000 stored bytes in each window of 25 hours, so after any other answer a retry runs again. A request that never finished answers 409 for up to 120 seconds and then runs again. Before a replay is answered it passes the limit checks that come before every request runs, so it can answer 429, and it shows the resource as it was at the first answer.

Optimistic concurrency

A resource you can change carries an etag. Send it as If-Match: if the resource changed since you read it, the answer is 412 precondition_failed. An operation on something that has no etag yet (creating a region rule, moving cookies into a category, a language's first banner texts) answers 412 for any well-formed If-Match, so send it without the header.

Rate limits

Each API key may send 300 requests a minute and each organisation 600. Of those, writes are limited to 60 a minute for each key and 120 for each organisation. Some operations add limits of their own. Each of these limits counts in a fixed window that opens with the first counted request, so around the end of a window up to twice a figure can pass in a short time. X-RateLimit-Limit and X-RateLimit-Remaining show the tightest one. Past a limit the answer is 429 rate_limited: wait the seconds in Retry-After. An organisation can have at most 2 requests running at once, and another one answers 429 concurrency_limited.

Untrusted fields

Members named in an answer's untrusted_fields hold text that a scanned website, a visitor's browser or a person wrote. Control characters are removed but markup is not, so escape each such value wherever you render it.

Versioning

The version is part of the path, /v1. New operations, members, values and optional parameters can arrive at any time, so ignore members and enum values you do not know. A change that could break your software, retiring the version included, takes effect only after at least 12 months' notice, or comes only in a new version. A security fix or a legal requirement can need less notice. The API Terms hold the full promise.

API

The API itself: its descriptor and this OpenAPI document.

Read the API descriptor

GET /v1

No API key needed.

The API's version and where its documentation is. Each IP address may call it 60 times a minute (an IPv6 /64 counts as one address).

Needs no API key.

Example request

curl "https://api.kukie.io/v1"

Answers

200 OK. The body is the api object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Read the OpenAPI document

GET /v1/openapi.json

No API key needed.

This API's OpenAPI document, the same for every caller. The answer may be cached for five minutes (Cache-Control: public, max-age=300) and carries an ETag: send it as If-None-Match and an unchanged document answers 304 with no body. Each IP address may call it 30 times a minute (an IPv6 /64 counts as one address).

Needs no API key.

Example request

curl "https://api.kukie.io/v1/openapi.json"

Answers

200 The OpenAPI document, as JSON. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag, Cache-Control.

304 The document is unchanged since the ETag you sent as If-None-Match. The answer has no body. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag, Cache-Control.

Errors

Scan reports

The scan report of a scan that ran to its end, and its JSON Schema.

Read the scan report schema

GET /v1/schemas/scan-report-1.json

No API key needed.

The JSON Schema (draft 2020-12) of version 1 of the scan report, the address every report names in its $schema member. The same for every caller, answered without an API key. Each IP address may call it and the OpenAPI document together 30 times a minute (an IPv6 /64 counts as one address).

Scan reports are not switched on yet. Until Kukie.io announces them in the API changelog, this operation answers 404 not_found.

Needs no API key.

Example request

curl "https://api.kukie.io/v1/schemas/scan-report-1.json"

Answers

200 The JSON Schema, as JSON. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Read a scan report

GET /v1/sites/{siteKey}/scans/{scanId}/report

Permission: reports:read.

Returns the scan report of a scan that ran to its end (completed or completed_with_errors): one JSON document with what the scan covered, the cookies and storage it found, the requests and providers, the banner check, its findings and the result of each check. The report is in English, with rule ids that do not change, so you can translate by them. Its JSON Schema is at GET /v1/schemas/scan-report-1.json, the address in its $schema member. Members can come in any order: read them by name. Every value untrusted_fields names comes from the scanned website: escape it before you show it. Works for a frozen site too.

The answer carries an ETag, the report's content_hash: send it as If-None-Match and an unchanged report answers 304 with no body.

While the scan waits or runs, the answer is 409 report_not_ready with Retry-After: 30. A report is built when its scan ends. A scan that ended before reports were available has its report built the first time it is asked for, and until then the answer is 409 report_not_ready with Retry-After: 10. Requests of your organisation start up to 20 such builds in each window of 60 seconds, and one more when two of your requests arrive at the same moment; past that, the answer is the same 409, so ask again after Retry-After. A scan that failed has no report and answers 404 not_found, as an unknown scan does. A report is deleted with its scan.

API keys created before this permission existed do not have it, whatever their permissions: create a new key that has it. Rolling a key keeps its permissions.

Scan reports are not switched on yet. Until Kukie.io announces them in the API changelog, this operation answers 404 not_found.

Needs the reports:read permission.

Path parameters

Read a scan report: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
scanId Required string format uuid The scan's id, the id of the scan object.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/scans/4a6f0c2e-9b1d-4c3a-8e5f-7d2b1a0c9e8f/report" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 The scan report. Its JSON Schema: GET /v1/schemas/scan-report-1.json. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag.

304 The report is unchanged since the ETag you sent as If-None-Match. The answer has no body. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag.

Errors

Download a scan report as PDF

GET /v1/sites/{siteKey}/scans/{scanId}/report/pdf

Permission: reports:read.

Returns the scan report of a scan that ran to its end as one PDF file, printed from the same stored document GET .../report returns, so the two never differ. The PDF is A4 and in English; its footer carries the report's content_hash. The address has no .pdf extension. Works for a frozen site too.

A PDF is made the first time it is asked for. Until it is ready the answer is 409 report_not_ready with Retry-After: 15: ask again after that. Asking again while it is being made queues nothing more. Your organisation can have up to 10 PDFs waiting to be made at once; past that, the answer is 429 queue_full with Retry-After. While the scan waits or runs, or its report is still being built, the answers are those of GET .../report.

When a PDF can't be made, the answer is 404 not_found, and the JSON report is still there. A request 15 minutes or more after the failed try makes one more try. A scan that failed has no report and answers 404 not_found, as an unknown scan does. A PDF is deleted with its scan or its site.

The answer is the file itself, Content-Type: application/pdf, with Content-Disposition: attachment and an ETag, the PDF's SHA-256: send it as If-None-Match and an unchanged PDF answers 304 with no body. Answers are never cached (Cache-Control: no-store, private).

Scan reports are not switched on yet. Until Kukie.io announces them in the API changelog, this operation answers 404 not_found.

Needs the reports:read permission.

Path parameters

Download a scan report as PDF: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
scanId Required string format uuid The scan's id, the id of the scan object.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/scans/4a6f0c2e-9b1d-4c3a-8e5f-7d2b1a0c9e8f/report/pdf" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 The scan report as a PDF file. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag, Content-Disposition.

304 The PDF is unchanged since the ETag you sent as If-None-Match. The answer has no body. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag, Content-Disposition.

Errors

Account

The calling API key, its organisation and plan, and your API traffic.

Read the account

GET /v1/account

Any API key, whatever its permissions.

Who the calling API key is, its organisation's plan with its limits and features, how many sites the key reaches and the general rate limits. It answers even when your plan no longer includes the API, so you can see why other operations answer 403 plan_upgrade_required: plan.api_access is then false.

Needs an API key, with any permissions.

Example request

curl "https://api.kukie.io/v1/account" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the account object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Read API usage

GET /v1/usage

Any API key, whatever its permissions.

Your API traffic for a window of whole UTC days, both ends included, grouped by day, by API key or by operation. A key that reaches every site sees the traffic of every key of its organisation, revoked keys included. A key that reaches only selected sites sees its own traffic only. A request sent with a valid key counts once its answer has gone out, this one included. Not counted: a request refused with 401 (a missing, unknown, expired or revoked key) and the 429 that repeated 401s bring; a request answered before the key is looked at (an address or a method the API does not have, an OPTIONS request, a malformed address, a credential in the URL, a body that is too large, any request while the API is unavailable); and the two operations that take no key. There is no split by site, and a group with no requests has no row.

With neither date the window is the last 30 days, today included. With from alone it runs to today or for 92 days, whichever ends first. With to alone it holds the 30 days up to to, but none before the oldest day kept. A cursor works only for the window it was made for, so to page through a window that a missing date fills in, send both dates, or the next page can answer 400 after midnight UTC.

A 503 service_unavailable means the figures took too long to compute: wait the seconds Retry-After gives (60), then try again with a shorter window.

Needs an API key, with any permissions.

Query parameters

Read API usage: query parameters
Name Type Description
from string format date The first day of the window, as YYYY-MM-DD in UTC. On or before to, no earlier than 13 months before today (usage is kept that long). The window holds at most 92 days.
to string format date The last day of the window, as YYYY-MM-DD in UTC: today or an earlier day.
group_by string, one of: day, key, operation default day How the rows are grouped: day (oldest first), key (by key id) or operation (in an order that stays the same between pages).
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/usage" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds usage_record objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Read API usage: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.
group_by string, one of: day, key, operation How the rows are grouped.
from string format date The first day of the window the answer covers.
to string format date The last day of the window the answer covers.

Errors

Sites

The websites of your organisation that run the Kukie.io banner: list, read, create, change and delete them, and check that the banner is installed.

List sites

GET /v1/sites

Permission: sites:read.

Returns the sites your API key can reach, newest first. A key that reaches selected sites lists only those.

The filters are exact matches and combine with AND. A query parameter this operation does not know is refused with 422, so a mistyped filter never returns the whole list. A cursor works only with the filters it was made with.

Needs the sites:read permission.

Query parameters

List sites: query parameters
Name Type Description
external_id string minimum length 1, maximum length 255 Only the site with this external_id, compared exactly and case sensitive. From 1 to 255 characters with no control or invisible characters.
domain string minimum length 1, maximum length 255 Only the site with this domain, up to 255 characters, such as example.com. A scheme, port, path, query, fragment, upper case and a trailing dot are removed before the comparison, and an internationalised domain name is compared in its ASCII form.
status string, one of: awaiting_setup, live, frozen_grace, frozen Only the sites with this status.
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/sites" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds site objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List sites: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.

Errors

Create a site

POST /v1/sites

Permission: sites:write.

Creates a site that starts like one created in the dashboard: Google Consent Mode on with Google's banner text, unless you send google_consent_mode as false or your plan does not include Consent Mode. Only an API key that reaches all sites can create one; a key that reaches selected sites answers 403 insufficient_scope.

With copy_settings_from the new site takes what a copy of settings takes from that site: the banner settings (apart from those that belong to each site, such as its Google Tag Manager, Matomo and Advanced analytics settings and its cookie domain), every language's texts and the region rules (the first ones in their order up to your plan's limit, counting rules that are switched off). It never takes that site's cookies or services, its consent logging switch or its scan frequency. It takes the accessibility widget's settings and texts only when the API key also has the accessibility:write permission. Without it the new site starts with the default widget, and when the copied site's widget differs from that, the answer carries the warning accessibility_widget_not_copied. This also needs the banner:write permission (403 insufficient_scope with required_scope otherwise) and a plan with copying settings between sites (403 plan_upgrade_required with feature: "site_settings_copy" and upgrade_url otherwise). The copied settings decide whether Consent Mode is on.

A domain or external_id another site of your organisation already has answers 409 conflict, with existing_site_id when your key can read that site. When your plan has no sites left the answer is 403 site_limit_reached with upgrade_url.

An organisation can create 10 sites a minute, 300 an hour and 1,000 a day through the API. Only a created site counts, not a refusal or a replay. A created site also counts as one banner rebuild toward the budget that every write which rebuilds a banner shares: 60 in each window of 300 seconds and 24 in each 60 seconds for your organisation. Kukie.io also limits rebuilds across all organisations, so a 429 rate_limited can come before your own limits are reached. Send the same Idempotency-Key when you retry: a retry gets the first answer back while it is stored, without its Location header, and after that the 409 conflict for the domain, never a second site.

Needs the sites:write permission.

Request headers

Create a site: request headers
Name Type Description
Idempotency-Key Required string minimum length 1, maximum length 255 A value of your own that names this request, so that sending the request again after a timeout returns the first answer while it is stored, in place of doing the work again: the same key with the same request answers with the first answer and Idempotent-Replayed: true. This operation needs it.

Request body

A JSON object. The body is required.

Create a site: request body
Name Type Description
domain Required string The site's domain name, such as example.com, up to 255 characters once normalised. A scheme, upper case, surrounding spaces, a trailing dot and an internationalised name are accepted and normalised. A path (a trailing slash included), query, fragment, port or user name is refused.
external_id string or null minimum length 1, maximum length 255 Your own identifier for the site, or null for none. From 1 to 255 characters, no control or invisible characters, no space at either end, and not shaped like an API key (it can't start with kk_ or contain kk_live_ or kk_test_, in any case). Unique in your organisation and case sensitive.
metadata object or null maximum members 20, each value: maximum length 500, each key: minimum length 1, maximum length 40 An object of up to 20 keys, each key 1 to 40 characters with no control characters, each value a string of up to 500 characters with no control characters other than tab, line feed and carriage return, and 8,192 bytes in all as compact JSON. It replaces the stored object whole, it is never merged. null or {} clears it. Keys can come back in another order. Do not store personal or sensitive data here.
google_consent_mode boolean default true Whether to turn on Google Consent Mode. Can't be sent with copy_settings_from, which takes the setting from the copied site.
copy_settings_from string or null format uuid The id of one of your sites to copy the settings from. Needs the banner:write permission too. A site your key cannot reach answers 422 like an id that does not exist. A frozen site can be copied from.

Example request

curl -X POST "https://api.kukie.io/v1/sites" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Idempotency-Key: 5f0c1d1e-7a41-4b0e-9c57-2d1f3b6a8e90" \
  -H "Content-Type: application/json" \
  -d '{"domain":"shop.example.com","external_id":"customer-4821"}'

Answers

201 Created. The site, whether Google Consent Mode is on, and any warnings. The body is the site object with the members below. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Idempotent-Replayed, Location.

Create a site: answer 201
Name Type Description
google_consent_mode boolean Whether Google Consent Mode is on for the new site, as it took effect.
warnings array of objects What did not happen as you asked. Empty when everything did.
warnings[].code string, one of: consent_mode_not_in_plan, consent_mode_off_in_copied_settings, region_rules_skipped, settings_copy_failed, accessibility_widget_not_copied The stable name of the warning. New codes can be added.
warnings[].message string What the warning means, in English for a developer. Its wording can change, so read code.

Errors

Get a site

GET /v1/sites/{siteKey}

Permission: sites:read.

Returns one site. A site of another organisation, or one your API key does not reach, answers 404 like a site that does not exist. Frozen sites can be read.

Needs the sites:read permission.

Path parameters

Get a site: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the site object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Update a site

PATCH /v1/sites/{siteKey}

Permission: sites:write.

Changes a site's external_id and metadata, nothing else. A member you send replaces the stored value; a member you leave out stays. Frozen sites can be updated.

An external_id another site of your organisation already uses answers 409 conflict, with existing_site_id when your key can read that site.

Needs the sites:write permission.

Path parameters

Update a site: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Request body

A JSON object. The body is required.

Update a site: request body
Name Type Description
external_id string or null minimum length 1, maximum length 255 Your own identifier for the site, or null for none. From 1 to 255 characters, no control or invisible characters, no space at either end, and not shaped like an API key (it can't start with kk_ or contain kk_live_ or kk_test_, in any case). Unique in your organisation and case sensitive.
metadata object or null maximum members 20, each value: maximum length 500, each key: minimum length 1, maximum length 40 An object of up to 20 keys, each key 1 to 40 characters with no control characters, each value a string of up to 500 characters with no control characters other than tab, line feed and carriage return, and 8,192 bytes in all as compact JSON. It replaces the stored object whole, it is never merged. null or {} clears it. Keys can come back in another order. Do not store personal or sensitive data here.

Example request

curl -X PATCH "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"customer-4821"}'

Answers

200 OK. The body is the site object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Delete a site

DELETE /v1/sites/{siteKey}

Permission: sites:delete.

Deletes a site and its consent records at once. They can't be restored, so the request needs confirm_consent_records_deletion=true in the query string; without it, or with another value, the answer is 422. Frozen sites can be deleted. The organisation's owner gets an email about the deletion, unless they turned those emails off. The owner and every admin also get a security email that names the API key and the deleted sites, soon after the first deletion and then at most once an hour; no setting stops it. Deleting the same site again answers 404.

An organisation can delete 10 sites a minute and 200 a day through the API. Only a deleted site counts. A deleted site also counts as one banner rebuild toward the budget that every write which rebuilds a banner shares: 60 in each window of 300 seconds and 24 in each 60 seconds for your organisation. Kukie.io also limits rebuilds across all organisations, so a 429 rate_limited can come before your own limits are reached.

Needs the sites:delete permission.

Path parameters

Delete a site: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Query parameters

Delete a site: query parameters
Name Type Description
confirm_consent_records_deletion Required string, one of: true Must be true: it confirms that the site's consent records are deleted with it, for good.

Example request

curl -X DELETE "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e?confirm_consent_records_deletion=true" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

204 Done. The answer has no body. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Check the banner installation

POST /v1/sites/{siteKey}/installation-check

Permission: sites:write.

Checks whether the Kukie.io banner is installed on the site, the same check as in the dashboard. The check runs before the answer is sent, so it can take some seconds. Every outcome of a check that ran answers 200; read installed and outcome. A confirmed installation sets the site's verified_at. Frozen sites can be checked. The request has no body.

Your organisation can run one check at a time. When another check is running for your organisation or for this site, or the API is running as many checks as it allows at once, the answer is 429 concurrency_limited with Retry-After: 30. When the check can't start because of a fault in Kukie.io, the answer is 503 service_unavailable with Retry-After.

You can check a site 1 time a minute, and your organisation can run 60 checks an hour. Only a check that ran counts, not a refusal or a replay.

The url_checked, message and content_security_policy_fixes[].value values come from the checked site, as untrusted_fields lists: escape them before you render them.

Needs the sites:write permission.

Path parameters

Check the banner installation: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Request headers

Check the banner installation: request headers
Name Type Description
Idempotency-Key string minimum length 1, maximum length 255 A value of your own that names this request, so that sending the request again after a timeout returns the first answer while it is stored, in place of doing the work again: the same key with the same request answers with the first answer and Idempotent-Replayed: true.

Example request

curl -X POST "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/installation-check" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 The check ran. The body says what it found. The body is the installation_check object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Idempotent-Replayed.

Errors

Copy a site's settings to other sites

POST /v1/sites/{siteKey}/copy-settings

Permission: banner:write.

Applies the settings of the site in the path to up to 100 other sites of your organisation: the banner settings (apart from those that belong to each site, such as its Google Tag Manager, Matomo and Advanced analytics settings and its cookie domain), every language's texts, the region rules (the first ones in their order up to your plan's limit, counting rules that are switched off), and on request the cookies added by hand and your own services. Unlike the dashboard's paste, it never copies the consent logging switch or the scan frequency. It copies the accessibility widget's settings and texts only when the API key also has the accessibility:write permission. Without it each target keeps its own widget, and a target whose widget differs from the source's gets the warning accessibility_widget_not_copied. A copy changes each target's banner etag, so a change sent with the target's older etag answers 412. It needs a plan with settings copying: otherwise the answer is 403 plan_upgrade_required with feature set to site_settings_copy and an upgrade_url.

A target outside the API key's reach, or the source itself, refuses the whole request with 422 before anything is written, naming target_sites.N (its place in your list) with the code not_found. A frozen target is skipped without being touched. Each other target is copied on its own, so one that fails leaves the others copied. You can copy from a frozen site.

Your organisation may copy to at most 100 target sites in a window of 300 seconds, counting only targets that are not frozen, and a copy also uses the budgets for banner rebuilds that every banner change shares: one rebuild for each 30 targets that are not frozen, or part of 30 toward your organisation's 60 in each window of 300 seconds and 24 in each 60 seconds, and each such target toward its 200 rebuilt sites in each window of 300 seconds. Kukie.io also limits rebuilds across all organisations. Past any of them the answer is 429 rate_limited with Retry-After, the seconds until the window of the limit that refused it ends, and no X-RateLimit-* headers. Nothing is copied then, and nothing counts toward these budgets. A retry with the same Idempotency-Key answers with the stored result, unless the answer was larger than 65536 bytes, which is not stored.

Needs the banner:write permission.

Path parameters

Copy a site's settings to other sites: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Request headers

Copy a site's settings to other sites: request headers
Name Type Description
Idempotency-Key string minimum length 1, maximum length 255 A value of your own that names this request, so that sending the request again after a timeout returns the first answer while it is stored, in place of doing the work again: the same key with the same request answers with the first answer and Idempotent-Replayed: true.

Request body

A JSON object. The body is required.

Copy a site's settings to other sites: request body
Name Type Description
target_sites Required array of strings minimum items 1, maximum items 100, each item: format uuid The ids of the sites to copy the settings to, 1 to 100. An id sent more than once, in any letter case, counts once.
include_cookies boolean default false Also copy the cookies added to the source by hand. A cookie whose category the target lacks is not copied.
include_services boolean default false Also copy your own services of the source. A service whose category the target lacks is not copied.

Example request

curl -X POST "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/copy-settings" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_sites":["7c1e5a2d-8f3b-4d6c-b0a9-1e2f3a4b5c6d"]}'

Answers

200 OK. The body is the settings_copy object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Idempotent-Replayed.

Errors

Banner

A site's banner settings, the banner on or off switch, and the banner texts of each language.

Get banner settings

GET /v1/sites/{siteKey}/banner

Permission: banner:read.

Returns the site's banner settings, with their version as the ETag header. A site that has no banner settings yet answers 404 not_found: save the banner once in the Banner Editor.

Needs the banner:read permission.

Path parameters

Get banner settings: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/banner" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the banner_settings object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag.

Errors

Change banner settings

PATCH /v1/sites/{siteKey}/banner

Permission: banner:write.

Changes the settings you send and leaves every setting you leave out as it is. A block (theme, revisit_button, iframe_placeholder, preferences_modal) is merged one level deep, so {"theme": {"primary_color": "#000000"}} changes one colour; a list is replaced whole. Send banner_enabled to turn the banner on or off. An empty body changes nothing.

The read-only members of the GET answer are accepted and ignored, so you can change a GET body and send it back. A member the endpoint does not know is refused with 422 validation_failed, at most 10 named. The values go through the Banner Editor's own checks; a refusal is 422 validation_failed with at most 50 entries. An object or list in the body holds at most 200 members, the whole body at most 2,000, and every key is 1 to 64 letters, digits, hyphens or underscores.

A value equal to the stored one is not a change. When nothing would change, nothing is written and the answer is the current settings. On a plan without the feature, a sent logo_url, custom_css, iframe_placeholder.custom_css, show_title_icon or the preferences window's icon and logo settings are not stored, and every settings change stores show_branding as true. warnings says so for logo_url, the custom CSS, show_title_icon and a show_branding of false.

Send the etag you read as If-Match: without it, the last write wins, and a GET body sent back puts back every setting someone else changed in between. A 412 can follow a change you did not make, such as a save of the site's other settings in the dashboard or the WordPress plugin: read the settings again and retry. A frozen site refuses the change with 403 site_frozen, and a site with no banner settings yet answers 404 not_found.

A write that changes something counts against your organisation's budget for banner rebuilds, which every write that rebuilds a banner shares: 60 for each window of 300 seconds, a window opening with the first such write, and 24 in each 60 seconds. Writes that rebuild many banners at once, such as a settings copy to many sites, use more of it. A write that changes nothing, or is refused, does not count. A limit that all organisations share can also answer 429, with Retry-After and without the rate limit headers.

Needs the banner:write permission.

Path parameters

Change banner settings: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Request headers

Change banner settings: request headers
Name Type Description
If-Match string The etag you last read. The change is made only if the resource still has it; otherwise the answer is 412 precondition_failed.

Request body

A JSON object. The body is optional.

Change banner settings: request body
Name Type Description
layout string, one of: popup, bar-bottom, bar-top, floating How the banner shows: a popup, a bar at the bottom or the top of the page, or a floating box.
position string, one of: center, bottom-left, bottom-center, bottom-right or null Where a floating banner sits on the page. Needed when layout is floating.
theme object The banner's colours, corner radii and button styles. Colours take a hex value or a var(--name) token of your page. Merged one level deep: the members you send change, the others stay. Send {} to change nothing. A member the block does not have is refused, unless it repeats what the block already holds.
theme.primary_color string maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback.
theme.bg_color string maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback.
theme.text_color string maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback.
theme.button_text_color string maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback.
theme.border_radius string maximum length 20, pattern ^(0|[0-9]{1,4}(\.[0-9]{1,2})?(px|em|rem|%))$ Text in the format shown.
theme.button_border_radius string or null maximum length 20, pattern ^(0|[0-9]{1,4}(\.[0-9]{1,2})?(px|em|rem|%))$ Text in the format shown. Null when not set.
theme.dark_primary_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_button_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_hover_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_hover_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_hover_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_hover_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_hover_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_hover_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_border_width string or null maximum length 10, pattern ^(0|[0-9]{1,2}(\.[0-9]{1,2})?(px)?)$ Text in the format shown. Null when not set.
theme.reject_btn_border_width string or null maximum length 10, pattern ^(0|[0-9]{1,2}(\.[0-9]{1,2})?(px)?)$ Text in the format shown. Null when not set.
theme.customize_btn_border_width string or null maximum length 10, pattern ^(0|[0-9]{1,2}(\.[0-9]{1,2})?(px)?)$ Text in the format shown. Null when not set.
theme.accept_btn_bold boolean or null True or false. Null when not set.
theme.reject_btn_bold boolean or null True or false. Null when not set.
theme.customize_btn_bold boolean or null True or false. Null when not set.
color_source string, one of: custom, inherit custom uses the theme's primary colour; inherit takes the primary colour from the visitor's page where the page declares one.
font_source string, one of: system, inherit system uses the device's system font; inherit uses the font of the visitor's page.
auto_dark_mode boolean Whether the banner uses dark colours when the visitor's device is set to a dark appearance.
dark_mode_source string, one of: auto, custom auto picks the dark colours for you; custom uses the theme's dark_ colours.
custom_css string or null maximum length 10000 Your own CSS for the banner. Used only on a plan with custom CSS.
show_branding boolean Whether the banner shows the Kukie.io branding. It stays on unless your plan includes removing it.
show_overlay boolean Whether a popup banner darkens the page behind it.
disabled_pages array of strings each item: maximum length 500 Page address patterns where the banner is not shown. Send the whole list: it replaces the stored one.
auto_block_scripts boolean Whether known tracking scripts are held until the visitor consents.
respect_dnt boolean Whether the banner honours the browser's Do Not Track signal.
respect_gpc boolean Whether the banner honours the browser's Global Privacy Control signal.
gcm_v2_enabled boolean Whether the banner sends Google Consent Mode signals.
gcm_url_passthrough boolean Whether Google Consent Mode passes ad click information through page addresses.
gtm_enabled boolean Whether the banner loads your Google Tag Manager container.
gtm_container_id string or null maximum length 20 The Google Tag Manager container to load, such as GTM-ABC123.
gtm_before_consent boolean Whether the container loads before the visitor makes a choice, instead of after it.
matomo_enabled boolean Whether the banner tells your Matomo tracker about the visitor's choice.
matomo_site_id string or null maximum length 20, pattern ^\d*$ Your Matomo site id, digits only.
matomo_tracker_url string or null format uri, maximum length 500 The address of your Matomo tracker.
ms_uet_enabled boolean Whether the banner sends Microsoft UET consent signals.
clarity_consent_enabled boolean Whether the banner sends Microsoft Clarity consent signals.
amazon_consent_enabled boolean Whether the banner sends Amazon consent signals.
iframe_blocking_enabled boolean Whether embedded content from known services is held until the visitor consents.
blocked_iframe_services array of strings or null, each item one of: youtube, vimeo, dailymotion, google-maps, facebook, instagram, twitter, tiktok, linkedin, spotify, recaptcha, hubspot The embedded services held until consent. Send the whole list: it replaces the stored one.
iframe_placeholder object or null How the placeholder shown in place of held embedded content looks. Its custom_css is used only on a plan with custom CSS. Merged one level deep: the members you send change, the others stay. Send {} to change nothing. A member the block does not have is refused, unless it repeats what the block already holds.
iframe_placeholder.inherit_layout boolean or null True or false. Null when not set.
iframe_placeholder.bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.bg_transparent boolean or null True or false. Null when not set.
iframe_placeholder.text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.border_width string or null maximum length 10, pattern ^(0|[0-9]{1,2}(\.[0-9]{1,2})?(px)?)$ Text in the format shown. Null when not set.
iframe_placeholder.border_radius string or null maximum length 20, pattern ^(0|[0-9]{1,4}(\.[0-9]{1,2})?(px|em|rem|%))$ Text in the format shown. Null when not set.
iframe_placeholder.min_height string or null maximum length 20, pattern ^(0|[0-9]{1,4}(\.[0-9]{1,2})?(px|em|rem|%|vh)?)$ Text in the format shown. Null when not set.
iframe_placeholder.accept_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.accept_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.accept_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.accept_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.accept_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.button_border_radius string or null maximum length 20, pattern ^(0|[0-9]{1,4}(\.[0-9]{1,2})?(px|em|rem|%))$ Text in the format shown. Null when not set.
iframe_placeholder.show_icon boolean or null True or false. Null when not set.
iframe_placeholder.show_service_name boolean or null True or false. Null when not set.
iframe_placeholder.show_preferences_button boolean or null True or false. Null when not set.
iframe_placeholder.custom_css string or null maximum length 10000 Text. Null when not set.
preferences_modal object or null How the preferences window looks and what it shows. Its texts map holds a title, a description and a privacy request link text for each language. Its icon and logo settings are used only on a plan that includes removing the branding. Merged one level deep: the members you send change, the others stay. Send {} to change nothing. A member the block does not have is refused, unless it repeats what the block already holds.
preferences_modal.button_layout string, one of: stacked, row or null One of the listed values. Null when not set.
preferences_modal.button_order array of strings or null, each item one of: save, reject, accept Text. Null when not set.
preferences_modal.max_width string or null maximum length 10, pattern ^[0-9]{3,4}(px)?$ Text in the format shown. Null when not set.
preferences_modal.show_policy_links boolean or null True or false. Null when not set.
preferences_modal.show_privacy_request_link boolean or null True or false. Null when not set.
preferences_modal.show_consent_id boolean or null True or false. Null when not set.
preferences_modal.show_overlay boolean or null True or false. Null when not set.
preferences_modal.custom_button_colors boolean or null True or false. Null when not set.
preferences_modal.show_icon boolean or null True or false. Null when not set.
preferences_modal.logo_url string or null format uri, maximum length 500 Text. Null when not set.
preferences_modal.logo_max_width integer or null minimum 40, maximum 100 A whole number. Null when not set.
preferences_modal.logo_border_radius integer or null minimum 0, maximum 50 A whole number. Null when not set.
preferences_modal.texts object or null Text. Null when not set.
preferences_modal.texts.*.title string or null maximum length 150 Text. Null when not set.
preferences_modal.texts.*.description string or null maximum length 500 Text. Null when not set.
preferences_modal.texts.*.privacy_request string or null maximum length 100 Text. Null when not set.
preferences_modal.accept_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_hover_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_hover_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_hover_bg_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_hover_text_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_hover_border_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
reload_on_consent boolean Whether the page reloads after the visitor makes a choice.
revisit_button object or null The button that lets a visitor open the banner again after a choice. Merged one level deep: the members you send change, the others stay. Send {} to change nothing. A member the block does not have is refused, unless it repeats what the block already holds.
revisit_button.enabled boolean True or false.
revisit_button.position string, one of: bottom_left, bottom_right, top_left, top_right or null One of the listed values. Null when not set.
revisit_button.style string, one of: icon, pill, tab or null One of the listed values. Null when not set.
revisit_button.icon string, one of: cookie, shield, settings, fingerprint, lock, sliders or null One of the listed values. Null when not set.
revisit_button.text string or null maximum length 100 Text. Null when not set.
revisit_button.color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
revisit_button.icon_color string or null maximum length 90, pattern ^(?:#[0-9a-fA-F]{3,8}|var\(--[A-Za-z0-9_-]{1,64}(?:\s*,\s*#[0-9a-fA-F]{3,8})?\))$ A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
revisit_button.offset_x integer or null minimum 0, maximum 200 A whole number. Null when not set.
revisit_button.offset_y integer or null minimum 0, maximum 200 A whole number. Null when not set.
auto_translate boolean Whether the banner shows in the visitor's language from the built-in translations.
default_language string or null maximum length 5 The language the banner falls back to.
enabled_languages array of strings or null each item: maximum length 10 The languages the banner may show in. Send the whole list: it replaces the stored one.
logo_url string or null format uri, maximum length 500 The address of a logo shown beside the banner title. Used only on a plan with a custom logo.
logo_max_width integer or null minimum 40, maximum 100 The logo's largest width, in pixels.
logo_border_radius integer or null minimum 0, maximum 50 The logo's corner radius, in pixels.
show_reject_all boolean Whether the banner shows the Reject all button.
show_customize boolean Whether the banner shows the button that opens the preferences.
show_close_button boolean Whether the banner shows a close button.
button_order array of strings or null, each item one of: customize, reject, accept The order of the banner's three buttons, each listed once. Null for the default order. Send the whole list: it replaces the stored one.
show_cookie_policy_link boolean Whether the banner shows the cookie policy link.
show_privacy_policy_link boolean Whether the banner shows the privacy policy link.
show_policy_links_in_banner boolean Whether the policy links show in the banner itself. When false they show only in the preferences window.
show_title_icon boolean Whether the banner shows the icon or logo beside its title. Used only on a plan that includes removing the branding.
banner_enabled boolean Turns the banner on or off. It changes even when the other stored settings would not pass the Banner Editor's checks.
object any Read only. Accepted and ignored, so you can send a GET body back. It locks nothing: use If-Match.
etag any Read only. Accepted and ignored, so you can send a GET body back. It locks nothing: use If-Match.
config_version any Read only. Accepted and ignored, so you can send a GET body back. It locks nothing: use If-Match.
google_consent_text_applied any Read only. Accepted and ignored, so you can send a GET body back. It locks nothing: use If-Match.
plan_limits any Read only. Accepted and ignored, so you can send a GET body back. It locks nothing: use If-Match.

Example request

curl -X PATCH "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/banner" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"show_reject_all":true}'

Answers

200 The settings as stored after the write, with warnings. The body is the banner_settings object with the members below. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag.

Change banner settings: answer 200
Name Type Description
warnings array of banner_warning objects What you should know about this write, such as a value your plan does not include. Empty when there is nothing to say. A warning never stops the write.

Errors

List banner texts

GET /v1/sites/{siteKey}/banner/texts

Permission: banner:read.

Returns the languages the site has banner texts for, in the order they were added. Each item is the object that getting the language returns, its etag included.

Needs the banner:read permission.

Path parameters

List banner texts: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Query parameters

List banner texts: query parameters
Name Type Description
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/banner/texts" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds banner_text objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List banner texts: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.

Errors

Get one language's banner texts

GET /v1/sites/{siteKey}/banner/texts/{locale}

Permission: banner:read.

Returns one language's banner texts, with their version as the ETag header. A language the site has no texts for answers 404 not_found.

Needs the banner:read permission.

Path parameters

Get one language's banner texts: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
locale Required string pattern ^[a-z]{2}(-[a-z]{2})?$ A language code: two lower-case letters, optionally followed by a hyphen and two more, such as de or pt-br.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/banner/texts/en" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the banner_text object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag.

Errors

Replace one language's banner texts

PUT /v1/sites/{siteKey}/banner/texts/{locale}

Permission: banner:write.

Replaces the language's whole text with the body. A text you leave out, or send as null or empty, is stored empty and the banner shows its built-in text for it, so an empty body clears every text. A language the site has no texts for yet is added, and the answer is then 201 with the same body. A site holds texts for at most 200 languages; adding one more is 422 validation_failed with the code limit_reached.

Texts are trimmed before they are stored. The read-only members of the GET answer are accepted, and locale, when sent, must be the path's. A member the endpoint does not know is refused with 422 validation_failed, at most 10 named. An object or list in the body holds at most 200 members, the whole body at most 2,000, and every key is 1 to 64 letters, digits, hyphens or underscores.

When the body would leave the texts and the default language as they are, nothing is written. The answer carries the new tag as its etag member and sends no ETag header, because the stored texts can differ from what you sent.

Send the etag you read as If-Match. A 412 can follow a change you did not make: moving the site's default language changes the tag of every language. A language with no texts yet has no tag, so any well-formed If-Match is 412 for it; leave the header out to add a language. A frozen site refuses the change with 403 site_frozen.

A write that changes something counts against your organisation's budget for banner rebuilds, which every write that rebuilds a banner shares: 60 for each window of 300 seconds, a window opening with the first such write, and 24 in each 60 seconds. Writes that rebuild many banners at once, such as a settings copy to many sites, use more of it. A write that changes nothing, or is refused, does not count. A limit that all organisations share can also answer 429, with Retry-After and without the rate limit headers.

Needs the banner:write permission.

Path parameters

Replace one language's banner texts: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
locale Required string pattern ^[a-z]{2}(-[a-z]{2})?$ A language code: two lower-case letters, optionally followed by a hyphen and two more, such as de or pt-br.

Request headers

Replace one language's banner texts: request headers
Name Type Description
If-Match string The etag you last read. The change is made only if the resource still has it; otherwise the answer is 412 precondition_failed.

Request body

A JSON object. The body is optional.

Replace one language's banner texts: request body
Name Type Description
title string or null maximum length 500 The banner's title. Left out, null or empty, it is stored empty and the banner shows its built-in text.
description string or null maximum length 5000 The banner's main text. It can hold a link and simple formatting, which are cleaned when the banner is built. Left out, null or empty, it is stored empty and the banner shows its built-in text.
accept_all_btn string or null maximum length 100 The label of the button that accepts all cookies. Left out, null or empty, it is stored empty and the banner shows its built-in text.
reject_all_btn string or null maximum length 100 The label of the button that rejects all cookies. Left out, null or empty, it is stored empty and the banner shows its built-in text.
customize_btn string or null maximum length 100 The label of the button that opens the preferences. Left out, null or empty, it is stored empty and the banner shows its built-in text.
save_preferences_btn string or null maximum length 100 The label of the button that saves the visitor's choices in the preferences. Left out, null or empty, it is stored empty and the banner shows its built-in text.
privacy_policy_text string or null maximum length 200 The words of the privacy policy link. Left out, null or empty, it is stored empty and the banner shows its built-in text.
privacy_policy_url string or null format uri, maximum length 500 The address the privacy policy link opens. Left out, null or empty, it is stored empty and the banner shows its built-in text.
cookie_policy_text string or null maximum length 200 The words of the cookie policy link. Left out, null or empty, it is stored empty and the banner shows its built-in text.
cookie_policy_url string or null format uri, maximum length 500 The address the cookie policy link opens. Left out, null or empty, it is stored empty and the banner shows its built-in text.
cookie_provider_label string or null maximum length 100 The label for a cookie's provider in the cookie details. Left out, null or empty, it is stored empty and the banner shows its built-in text.
cookie_duration_label string or null maximum length 100 The label for how long a cookie lasts in the cookie details. Left out, null or empty, it is stored empty and the banner shows its built-in text.
cookie_description_label string or null maximum length 100 The label for a cookie's description in the cookie details. Left out, null or empty, it is stored empty and the banner shows its built-in text.
no_cookies_detected_text string or null maximum length 255 The text shown where a category lists no cookies. Left out, null or empty, it is stored empty and the banner shows its built-in text.
category_texts object or null maximum members 50 The name and description of each cookie category, by the category's slug. A slug that is not 1 to 50 letters, digits, hyphens or underscores is left out. Left out, null or {}, the language keeps no category texts.
category_texts.*.name string or null maximum length 100 The category's name.
category_texts.*.description string or null maximum length 500 The category's description.
is_default boolean True makes this language the site's default. Left out or false, the default stays where it is; a site's first language becomes its default.
locale string Read only. Left out, or the language code of the path.
object any Read only. Accepted and ignored, so you can send a GET body back. It locks nothing: use If-Match.
etag any Read only. Accepted and ignored, so you can send a GET body back. It locks nothing: use If-Match.

Example request

curl -X PUT "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/banner/texts/en" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Cookies on this site"}'

Answers

200 The texts as stored, with warnings. A new language answers 201 with the same body. The body is the banner_text object with the members below. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Replace one language's banner texts: answer 200
Name Type Description
warnings array of banner_warning objects What you should know about this write, such as a value your plan does not include. Empty when there is nothing to say. A warning never stops the write.

201 The language was added. The body is the texts as stored, with warnings. The body is the banner_text object with the members below. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Replace one language's banner texts: answer 201
Name Type Description
warnings array of banner_warning objects What you should know about this write, such as a value your plan does not include. Empty when there is nothing to say. A warning never stops the write.

Errors

Region rules

The consent settings a site's banner uses for visitors in each region.

List a site's region rules

GET /v1/sites/{siteKey}/region-rules

Permission: banner:read.

Returns the site's region rules in the order the Banner Editor's Regions tab shows them (by sort_order). Each item is the rule its own GET returns, etag included.

Needs the banner:read permission.

Path parameters

List a site's region rules: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Query parameters

List a site's region rules: query parameters
Name Type Description
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/region-rules" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds region_rule objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List a site's region rules: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.

Errors

Create a region rule

POST /v1/sites/{siteKey}/region-rules

Permission: banner:write.

Creates the site's rule for one region. region_code and consent_model are required, and every setting you leave out starts at its default.

A region has at most one rule: a second one answers 409 conflict. When the plan's limit on active custom rules refuses the change, the answer is 403 plan_upgrade_required with feature: "region_rules" and upgrade_url. The Rest of World rule takes no place in that limit. A rule created with is_active: false takes no place either.

A rule that does not exist yet has no version, so do not send If-Match: any well-formed If-Match answers 412 precondition_failed and nothing is created. The answer carries the new rule's ETag and its Location. A replayed answer (the same Idempotency-Key again) carries neither header.

A change rebuilds the site's banner and counts toward your organisation's limit of 60 banner rebuilds in each window of 300 seconds and 24 in each 60 seconds, shared with every other operation that changes a banner. Kukie.io also limits rebuilds across all organisations, so a 429 rate_limited can come before your own limit is reached. A request that is refused or changes nothing is not counted.

Needs the banner:write permission.

Path parameters

Create a region rule: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Request headers

Create a region rule: request headers
Name Type Description
Idempotency-Key string minimum length 1, maximum length 255 A value of your own that names this request, so that sending the request again after a timeout returns the first answer while it is stored, in place of doing the work again: the same key with the same request answers with the first answer and Idempotent-Replayed: true.

Request body

A JSON object. The body is required.

Create a region rule: request body
Name Type Description
region_code Required string, one of: eu, uk, ch, us, ca, ca-qc, br, au, nz, za, jp, kr, in, default, eu-de, eu-fr, eu-it, eu-es, eu-nl, us-ca, us-va, us-co, us-ct, us-ut, us-tx, us-or, us-mt, us-ia, us-de, us-ne, us-nh, us-nj, us-tn, us-mn, us-md, us-in, us-ky, us-ri The region the rule is for. It never changes after the rule is created.
consent_model Required string, one of: opt_in, opt_out, notice_only, hidden How the banner asks for consent in this region: opt_in keeps cookies and tags waiting for the visitor's choice, opt_out and notice_only start with consent granted before the visitor chooses, and hidden shows no banner and starts with consent granted.
show_reject_all boolean default true Whether the banner shows Reject all in this region.
show_preferences boolean default true Whether the banner shows Manage preferences in this region.
show_accept_all boolean default true Whether the banner shows Accept all in this region.
cookie_wall_enabled boolean default false Whether an opt-in banner covers the page until the visitor chooses. It needs Accept all or Manage preferences, so visitors have a way past it, and has no effect with another consent model.
dismiss_on_scroll boolean default false For a notice_only banner: whether the notice closes with implied consent once the visitor scrolls further than dismiss_on_scroll_distance pixels without using it.
dismiss_on_scroll_distance integer default 200, minimum 50, maximum 1000 How far the visitor scrolls, in pixels, before the notice closes, from 50 to 1000.
dismiss_on_timeout boolean default false For a notice_only banner: whether the notice closes with implied consent after dismiss_timeout_seconds seconds without being used.
dismiss_timeout_seconds integer or null minimum 5, maximum 300 How many seconds the notice stays before it closes, from 5 to 300, or null when no time is set.
consent_duration_days integer default 365, minimum 1, maximum 730 How many days a visitor's choice is kept before the banner asks again, from 1 to 730.
reconsent_on_change boolean default true Whether visitors are asked again after the banner's configuration changes.
show_dnsmpi_link boolean default false Whether links on the site that carry the data-cc-dnsmpi attribute open the Do Not Sell or Share dialog in this region.
data_selling_opt_out boolean default false Stored with the rule. The banner does not read it.
is_active boolean default true Whether the rule is in use. A rule that is off is kept, and its visitors get the rule of the parent region or the Rest of World rule.
sort_order integer minimum 0, maximum 100000 The rule's place in the list, lowest first. Left out, the rule goes after every other rule of the site.
object any Read only: accepted and ignored, so you can send back a rule as you read it.
etag any Read only: accepted and ignored, so you can send back a rule as you read it.
quota_locked_at any Read only: accepted and ignored, so you can send back a rule as you read it.

Example request

curl -X POST "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/region-rules" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"region_code":"us-ca","consent_model":"opt_out"}'

Answers

201 Created. The body is the region_rule object with the members below. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag, Idempotent-Replayed, Location.

Create a region rule: answer 201
Name Type Description
warnings array of objects What a person changing this rule in the dashboard would be told. A warning never stops the change.
warnings[].code string, one of: reject_all_hidden_under_opt_in, accept_all_hidden_with_google_text, google_consent_first_places_granted The stable name of the warning. reject_all_hidden_under_opt_in: the rule uses opt-in and Reject all is hidden, by the rule or by the site's banner settings. accept_all_hidden_with_google_text: Google's banner text is applied, and it tells visitors to select Accept all, which the rule hides. google_consent_first_places_granted: Google Consent Mode is on, and the change leaves a place where Google asks for consent first (the EEA, the UK, Switzerland) on a rule that starts with consent granted. New codes can be added, so treat one you do not know as a message to show.
warnings[].message string The warning as a sentence for a person. Its wording can change.

Errors

Get a region rule

GET /v1/sites/{siteKey}/region-rules/{regionCode}

Permission: banner:read.

Returns one of the site's region rules. The ETag header holds its etag.

Needs the banner:read permission.

Path parameters

Get a region rule: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
regionCode Required string pattern ^[A-Za-z0-9_-]{1,10}$ The rule's region code, as its region_code holds it, for example eu, us-ca or default. It is matched exactly, so EU is not the eu rule.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/region-rules/us-ca" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the region_rule object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag.

Errors

Change a region rule

PATCH /v1/sites/{siteKey}/region-rules/{regionCode}

Permission: banner:write.

Changes the settings you send. A setting you leave out stays as it is, and a value equal to the stored one is not a change. When nothing changes, nothing is written and the answer is the rule as it stands, with its warnings.

The rule is checked whole, as the change would leave it: a cookie wall needs Accept all or Manage preferences, and a banner needs at least one button. So a rule stored under older checks can answer 422 for a setting you did not send. Switching a custom rule on clears quota_locked_at. When the plan's limit on active custom rules refuses the change, the answer is 403 plan_upgrade_required with feature: "region_rules" and upgrade_url. The Rest of World rule takes no place in that limit.

Send If-Match with the etag you read: without it, the last change wins. A 412 means the rule changed since you read it.

A change rebuilds the site's banner and counts toward your organisation's limit of 60 banner rebuilds in each window of 300 seconds and 24 in each 60 seconds, shared with every other operation that changes a banner. Kukie.io also limits rebuilds across all organisations, so a 429 rate_limited can come before your own limit is reached. A request that is refused or changes nothing is not counted.

Needs the banner:write permission.

Path parameters

Change a region rule: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
regionCode Required string pattern ^[A-Za-z0-9_-]{1,10}$ The rule's region code, as its region_code holds it, for example eu, us-ca or default. It is matched exactly, so EU is not the eu rule.

Request headers

Change a region rule: request headers
Name Type Description
If-Match string The etag you last read. The change is made only if the resource still has it; otherwise the answer is 412 precondition_failed.

Request body

A JSON object. The body is required.

Change a region rule: request body
Name Type Description
region_code string Only the code in the path, or leave it out: a rule's region never changes. To cover another region, delete this rule and create one for it.
consent_model string, one of: opt_in, opt_out, notice_only, hidden How the banner asks for consent in this region: opt_in keeps cookies and tags waiting for the visitor's choice, opt_out and notice_only start with consent granted before the visitor chooses, and hidden shows no banner and starts with consent granted.
show_reject_all boolean Whether the banner shows Reject all in this region.
show_preferences boolean Whether the banner shows Manage preferences in this region.
show_accept_all boolean Whether the banner shows Accept all in this region.
cookie_wall_enabled boolean Whether an opt-in banner covers the page until the visitor chooses. It needs Accept all or Manage preferences, so visitors have a way past it, and has no effect with another consent model.
dismiss_on_scroll boolean For a notice_only banner: whether the notice closes with implied consent once the visitor scrolls further than dismiss_on_scroll_distance pixels without using it.
dismiss_on_scroll_distance integer minimum 50, maximum 1000 How far the visitor scrolls, in pixels, before the notice closes, from 50 to 1000.
dismiss_on_timeout boolean For a notice_only banner: whether the notice closes with implied consent after dismiss_timeout_seconds seconds without being used.
dismiss_timeout_seconds integer or null minimum 5, maximum 300 How many seconds the notice stays before it closes, from 5 to 300, or null when no time is set.
consent_duration_days integer minimum 1, maximum 730 How many days a visitor's choice is kept before the banner asks again, from 1 to 730.
reconsent_on_change boolean Whether visitors are asked again after the banner's configuration changes.
show_dnsmpi_link boolean Whether links on the site that carry the data-cc-dnsmpi attribute open the Do Not Sell or Share dialog in this region.
data_selling_opt_out boolean Stored with the rule. The banner does not read it.
is_active boolean Whether the rule is in use. A rule that is off is kept, and its visitors get the rule of the parent region or the Rest of World rule.
sort_order integer minimum 0, maximum 100000 The rule's place in the list, lowest first, at most 100000. A larger value that is already stored may be sent back unchanged.
object any Read only: accepted and ignored, so you can send back a rule as you read it.
etag any Read only: accepted and ignored, so you can send back a rule as you read it.
quota_locked_at any Read only: accepted and ignored, so you can send back a rule as you read it.

Example request

curl -X PATCH "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/region-rules/us-ca" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"show_reject_all":true}'

Answers

200 OK. The body is the region_rule object with the members below. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag.

Change a region rule: answer 200
Name Type Description
warnings array of objects What a person changing this rule in the dashboard would be told. A warning never stops the change.
warnings[].code string, one of: reject_all_hidden_under_opt_in, accept_all_hidden_with_google_text, google_consent_first_places_granted The stable name of the warning. reject_all_hidden_under_opt_in: the rule uses opt-in and Reject all is hidden, by the rule or by the site's banner settings. accept_all_hidden_with_google_text: Google's banner text is applied, and it tells visitors to select Accept all, which the rule hides. google_consent_first_places_granted: Google Consent Mode is on, and the change leaves a place where Google asks for consent first (the EEA, the UK, Switzerland) on a rule that starts with consent granted. New codes can be added, so treat one you do not know as a message to show.
warnings[].message string The warning as a sentence for a person. Its wording can change.

Errors

Delete a region rule

DELETE /v1/sites/{siteKey}/region-rules/{regionCode}

Permission: banner:write.

Deletes one of the site's region rules. Its visitors then get the rule of the parent region or the Rest of World rule. The Rest of World rule (default) is never deleted: that answers 422 validation_failed.

The answer is the rule as it was, with deleted: true and warnings, and has no ETag header. Send If-Match with the etag you read: without it, the rule is deleted whatever changed since. A 412 means the rule changed since you read it.

A change rebuilds the site's banner and counts toward your organisation's limit of 60 banner rebuilds in each window of 300 seconds and 24 in each 60 seconds, shared with every other operation that changes a banner. Kukie.io also limits rebuilds across all organisations, so a 429 rate_limited can come before your own limit is reached. A request that is refused or changes nothing is not counted.

Needs the banner:write permission.

Path parameters

Delete a region rule: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
regionCode Required string pattern ^[A-Za-z0-9_-]{1,10}$ The rule's region code, as its region_code holds it, for example eu, us-ca or default. It is matched exactly, so EU is not the eu rule.

Request headers

Delete a region rule: request headers
Name Type Description
If-Match string The etag you last read. The change is made only if the resource still has it; otherwise the answer is 412 precondition_failed.

Example request

curl -X DELETE "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/region-rules/us-ca" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 Deleted. The body is the rule as it was. The body is the region_rule object with the members below. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Delete a region rule: answer 200
Name Type Description
deleted always true Always true: the rule is gone.
warnings array of objects What a person changing this rule in the dashboard would be told. A warning never stops the change.
warnings[].code string, one of: reject_all_hidden_under_opt_in, accept_all_hidden_with_google_text, google_consent_first_places_granted The stable name of the warning. reject_all_hidden_under_opt_in: the rule uses opt-in and Reject all is hidden, by the rule or by the site's banner settings. accept_all_hidden_with_google_text: Google's banner text is applied, and it tells visitors to select Accept all, which the rule hides. google_consent_first_places_granted: Google Consent Mode is on, and the change leaves a place where Google asks for consent first (the EEA, the UK, Switzerland) on a rule that starts with consent granted. New codes can be added, so treat one you do not know as a message to show.
warnings[].message string The warning as a sentence for a person. Its wording can change.

Errors

Cookies

The cookies a site's banner lists, their categories, and moving cookies into a category.

List a site's cookies

GET /v1/sites/{siteKey}/cookies

Permission: banner:read.

Returns the site's cookies in the order the banner lists them. untrusted_fields names the members whose text comes from a scanned site or a person: escape those values before you render them.

A cursor whose last cookie was deleted since (a later scan can retire a cookie) answers 400: start again from the first page.

Needs the banner:read permission.

Path parameters

List a site's cookies: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Query parameters

List a site's cookies: query parameters
Name Type Description
category string pattern ^[A-Za-z0-9_-]{1,50}$ A category's slug, as the category list returns it: only the cookies in that category. A slug the site has no category for answers 422.
needs_review string, one of: true, false true for only the cookies waiting for a category (see needs_review on the cookie). false is the same as leaving it out.
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/cookies" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds cookie objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List a site's cookies: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.
untrusted_fields array of strings, each item one of: data[].name, data[].domain, data[].path, data[].provider, data[].duration, data[].description, data[].type The members whose text comes from a scanned site or a person, as paths such as data[].name. That text is cleaned of control and invisible characters and cut to a length, but markup is left as it is: escape these values before you render them.

Errors

List a site's cookie categories

GET /v1/sites/{siteKey}/categories

Permission: banner:read.

Returns the site's cookie categories in the order the banner shows them. untrusted_fields names the members a person wrote: escape those values before you render them.

Needs the banner:read permission.

Path parameters

List a site's cookie categories: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Query parameters

List a site's cookie categories: query parameters
Name Type Description
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/categories" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds cookie_category objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List a site's cookie categories: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.
untrusted_fields array of strings, each item one of: data[].name, data[].description The members whose text comes from a scanned site or a person, as paths such as data[].name. That text is cleaned of control and invisible characters and cut to a length, but markup is left as it is: escape these values before you render them.

Errors

Move cookies into a category

POST /v1/sites/{siteKey}/cookies/categorise

Permission: banner:write.

Moves up to 100 of the site's cookies into one of its categories and marks them as categorised by hand, so a later scan keeps them there. The move stays within your organisation: it does not count towards how Kukie.io categorises these cookies for other sites.

If any id is not a cookie of this site, the answer is 422 with cookie_ids not_found, the same for every reason, and nothing moves. When every cookie is already in the category and categorised by hand, nothing is written and the answer is the same as for a move.

This action has no version, so do not send If-Match: any well-formed If-Match answers 412 precondition_failed and nothing moves.

A change rebuilds the site's banner and counts toward your organisation's limit of 60 banner rebuilds in each window of 300 seconds and 24 in each 60 seconds, shared with every other operation that changes a banner. Kukie.io also limits rebuilds across all organisations, so a 429 rate_limited can come before your own limit is reached. A request that is refused or changes nothing is not counted.

Needs the banner:write permission.

Path parameters

Move cookies into a category: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Request headers

Move cookies into a category: request headers
Name Type Description
Idempotency-Key string minimum length 1, maximum length 255 A value of your own that names this request, so that sending the request again after a timeout returns the first answer while it is stored, in place of doing the work again: the same key with the same request answers with the first answer and Idempotent-Replayed: true.

Request body

A JSON object. The body is required.

Move cookies into a category: request body
Name Type Description
cookie_ids Required array of strings minimum items 1, maximum items 100, no item twice, each item: pattern ^ck_[0-9a-f]{32}$ The ids of the cookies to move, as the cookie list returns them, each once.
category Required string pattern ^[A-Za-z0-9_-]{1,50}$ The slug of the category to move them into, as the category list returns it.

Example request

curl -X POST "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/cookies/categorise" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cookie_ids":["ck_3f2a9c0d1e4b5a6978c0d1e2f3a4b5c6"],"category":"analytics"}'

Answers

200 OK. The body is the cookie_categorisation object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Idempotent-Replayed.

Errors

Accessibility widget

The accessibility widget a site can show beside its banner: its settings and the site's own texts for its panel.

Get the accessibility widget settings

GET /v1/sites/{siteKey}/accessibility-widget

Permission: accessibility:read.

Returns the widget's settings. It answers whether or not your plan includes the widget: available says whether it does, enabled is the stored switch, and active is both, whether the site's script shows the widget. A plan that lost the widget keeps enabled as it was and reads available: false, active: false. A site with no banner settings yet answers 404: save the banner once in the Banner Editor first. The etag changes with any change to the 10 settings, whoever makes it, and with nothing else, not even a plan change.

Needs the accessibility:read permission.

Path parameters

Get the accessibility widget settings: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/accessibility-widget" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the accessibility_widget object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag.

Errors

Change the accessibility widget settings

PATCH /v1/sites/{siteKey}/accessibility-widget

Permission: accessibility:write.

Changes the settings the body names. A setting you leave out stays as it is, and the two lists, hidden_modules and languages, are replaced whole. A value equal to the stored one is not a change: when nothing changes, nothing is written and the answer is the widget as it stands.

Each value must have its JSON type (true or false, a whole number, text, a list of text), or the answer is 422 with the code invalid for that member. An unknown member is 422 unknown_parameter. A value that breaks a rule names the rule as the code, such as in or max. default_language must be one of the languages the widget has after the change, so a change of languages that drops the current default needs another default_language, or null, in the same body (422 invalid otherwise).

On a plan without the widget the answer is 403 plan_upgrade_required with feature: "accessibility_widget" and an upgrade_url, before the body is read. A frozen site answers 403 site_frozen. A site with no banner settings yet answers 404. With If-Match, a 412 means the settings changed since you read them, from the dashboard, the WordPress plugin or another API call. Without it the last write wins. Switching the widget on or off adds it to, or removes it from, the site's script.

A write that changes something rebuilds the site's script and counts as one rebuild toward your organisation's limit of 60 in each 300-second window, which starts with the first one, and 24 in each 60 seconds, shared with every other operation that rebuilds a script. The platform also limits rebuilds across all organisations, so a 429 rate_limited can come sooner. A write that changes nothing, or is refused, does not count.

Needs the accessibility:write permission.

Path parameters

Change the accessibility widget settings: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Request headers

Change the accessibility widget settings: request headers
Name Type Description
If-Match string The etag you last read. The change is made only if the resource still has it; otherwise the answer is 412 precondition_failed.

Request body

A JSON object. The body is required.

Change the accessibility widget settings: request body
Name Type Description
enabled boolean Switches the widget on or off. Your plan must include the widget for it to be shown.
position string, one of: bottom-right, bottom-left The bottom corner of the page the widget's button sits in.
color string or null pattern ^#[0-9a-fA-F]{6}$ The widget's colour, as #rrggbb. Send null, or an empty string, to use the banner's own colour.
hidden_modules array of strings, each item one of: textSize, spacing, lineHeight, dyslexia, bold, contrast, sat, align, scale, links, titles, motion, images, sound, cursor, guide, tts, profiles, structure, language maximum items 20 The panel's tools to hide, replacing the whole list. Send [] to show every tool. Repeated items count once.
hide_mobile boolean Whether the widget is hidden on screens up to 767 pixels wide.
size integer, one of: 44, 52, 60 The diameter of the widget's button, in pixels.
statement_enabled boolean Whether the panel shows a link to an accessibility statement.
statement_url string or null format uri, maximum length 500 An http or https address for the statement link. Send null, or an empty string, to use the site's published accessibility statement, when it has one.
languages array of strings or null, each item one of: ar, az, be, bg, bn, bs, ca, cs, cy, da, de, el, en, es-ar, es-mx, es, et, eu, fa, fi, fr, ga, gl, he, hi, hr, ht, hu, hy, id, is, it, ja, ka, kk, km, ko, lb, lt, lv, mi, mk, mn, ms, mt, my, ne, nl, no, pl, pt-br, pt, qu, ro, ru, si, sk, sl, sm, sq, sr, sv, th, tl, tr, uk, ur, uz, vi, zh-tw, zh maximum items 100 The languages the panel can be shown in, replacing the whole list. English is always added. Send [] or null to use the banner's languages and English. Repeated items count once.
default_language string, one of: ar, az, be, bg, bn, bs, ca, cs, cy, da, de, el, en, es-ar, es-mx, es, et, eu, fa, fi, fr, ga, gl, he, hi, hr, ht, hu, hy, id, is, it, ja, ka, kk, km, ko, lb, lt, lv, mi, mk, mn, ms, mt, my, ne, nl, no, pl, pt-br, pt, qu, ro, ru, si, sk, sl, sm, sq, sr, sv, th, tl, tr, uk, ur, uz, vi, zh-tw, zh or null The language the panel opens in. It must be one of the languages the widget has after this change. Send null, or an empty string, to let the widget pick the visitor's language.
object any Read only. Accepted and ignored, so you can send a GET answer back with your changes.
etag any Read only. Accepted and ignored, so you can send a GET answer back with your changes.
available any Read only. Accepted and ignored, so you can send a GET answer back with your changes.
active any Read only. Accepted and ignored, so you can send a GET answer back with your changes.

Example request

curl -X PATCH "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/accessibility-widget" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Answers

200 The widget's settings after the change. The body is the accessibility_widget object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, ETag.

Errors

List the accessibility widget texts

GET /v1/sites/{siteKey}/accessibility-widget/texts

Permission: accessibility:read.

Lists one text object for each language the site's widget includes: the widget's own language selection, or the banner's languages, plus English, in the order of their codes. strings holds the site's overrides, {} when the language has none. keys lists every key an override may set. It answers whether or not your plan includes the widget. An override stored for a language the widget no longer includes is not listed.

Needs the accessibility:read permission.

Path parameters

List the accessibility widget texts: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Query parameters

List the accessibility widget texts: query parameters
Name Type Description
include string, one of: defaults Send defaults to add each language's shipped texts as defaults. Any other value is 422 invalid.
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/accessibility-widget/texts" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds accessibility_widget_text objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List the accessibility widget texts: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.
keys array of strings, each item one of: panel_title, open_menu, close_menu, quick_profiles, adjustments, profile_motor, profile_low_vision, profile_dyslexia, profile_cognitive, profile_adhd, profile_seizure, content_scaling, scaling_decrease, scaling_increase, bigger_text, text_spacing, line_height, text_align, align_left, align_center, align_right, dyslexia_friendly, highlight_links, highlight_titles, bold_text, contrast, high_contrast, dark_mode, invert_colors, saturation, high_saturation, monochrome, low_saturation, hide_images, pause_animations, big_cursor, mute_sounds, reading_guide, guide_line, reading_mask, read_aloud, read_aloud_hint, page_structure, back, headings, landmarks, links, no_headings, no_landmarks, no_links, landmark_navigation, landmark_main, landmark_header, landmark_footer, landmark_complementary, reset_all, reset_done, state_on, state_off, level_of, saved_note, language, accessibility_statement Every text key an override may set.

Errors

Replace one language's widget texts

PUT /v1/sites/{siteKey}/accessibility-widget/texts/{locale}

Permission: accessibility:write.

Replaces the site's overrides for one language with the body's strings: the whole set, not a merge. A key you leave out, or send as null or an empty string, uses the shipped text again, and with no override left the language goes back to the shipped texts. What is stored is cleaned: markup is removed and each text is trimmed, so read the answer for what was stored. Each text is at most 500 characters, and level_of must keep both {n} and {m}.

A key of strings the widget has no text for is 422 unknown_parameter, named strings.<key>. A locale member that differs from the path, or strings that is not an object, is 422 invalid. A language the site's widget does not include is 422 not_allowed on locale, because its texts would never be shown: use a language the texts list returns.

On a plan without the widget the answer is 403 plan_upgrade_required with feature: "accessibility_widget" and an upgrade_url, before the body is read. A frozen site answers 403 site_frozen. A language without overrides has an etag too, so you can guard the first write with If-Match. A 412 means the language's overrides changed since you read them. The answer is always 200 with the text object, which carries its etag member but no ETag header, because what is stored is a cleaned copy of what you sent.

A write that changes something rebuilds the site's script and counts as one rebuild toward your organisation's limit of 60 in each 300-second window, which starts with the first one, and 24 in each 60 seconds, shared with every other operation that rebuilds a script. The platform also limits rebuilds across all organisations, so a 429 rate_limited can come sooner. A write that changes nothing, or is refused, does not count.

Needs the accessibility:write permission.

Path parameters

Replace one language's widget texts: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
locale Required string pattern ^[a-z]{2}(-[a-z]{2})?$ A language code: two lower-case letters, optionally followed by a hyphen and two more, such as de or pt-br.

Request headers

Replace one language's widget texts: request headers
Name Type Description
If-Match string The etag you last read. The change is made only if the resource still has it; otherwise the answer is 412 precondition_failed.

Request body

A JSON object. The body is required.

Replace one language's widget texts: request body
Name Type Description
strings Required object keys, each one of: panel_title, open_menu, close_menu, quick_profiles, adjustments, profile_motor, profile_low_vision, profile_dyslexia, profile_cognitive, profile_adhd, profile_seizure, content_scaling, scaling_decrease, scaling_increase, bigger_text, text_spacing, line_height, text_align, align_left, align_center, align_right, dyslexia_friendly, highlight_links, highlight_titles, bold_text, contrast, high_contrast, dark_mode, invert_colors, saturation, high_saturation, monochrome, low_saturation, hide_images, pause_animations, big_cursor, mute_sounds, reading_guide, guide_line, reading_mask, read_aloud, read_aloud_hint, page_structure, back, headings, landmarks, links, no_headings, no_landmarks, no_links, landmark_navigation, landmark_main, landmark_header, landmark_footer, landmark_complementary, reset_all, reset_done, state_on, state_off, level_of, saved_note, language, accessibility_statement, each value: maximum length 500 The language's whole set of overrides, each a key of keys with its text. A key left out, null or an empty string uses the shipped text. Send {} to remove every override.
object any Read only. Accepted and ignored.
etag any Read only. Accepted and ignored. Send the version you read as If-Match instead.
locale string Read only. If you send it, it must be the language in the path.
defaults any Read only. Accepted and ignored.

Example request

curl -X PUT "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/accessibility-widget/texts/en" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"strings":{"panel_title":"Accessibility options"}}'

Answers

200 The language's overrides as they were stored. The body is the accessibility_widget_text object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Scans

Cookie scans of a site: start one, follow it, and read the cookies it found.

List a site's scans

GET /v1/sites/{siteKey}/scans

Permission: scans:read.

Lists the site's cookie scans, newest first, whoever started them. Old scans are deleted every day: a finished scan created more than 30 days ago goes, with its scan report, except the site's 5 newest.

Needs the scans:read permission.

Path parameters

List a site's scans: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Query parameters

List a site's scans: query parameters
Name Type Description
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/scans" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds scan objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List a site's scans: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.

Errors

Start a cookie scan

POST /v1/sites/{siteKey}/scans

Permission: scans:write.

Starts a cookie scan of the site and answers at once with the new scan, before it has run. Read the scan at the Location address until its status is completed, completed_with_errors or failed, no more often than Retry-After says.

The request takes no query parameters and no body members: send no body or {}. One scan of a site runs at a time: while one waits or runs the answer is 409 scan_in_progress. Your organisation can have at most 50 waiting scans started through the API (scans started any other way do not count), and above that, or when the scan queue of Kukie.io is full, the answer is 429 queue_full with Retry-After. A frozen site answers 403 site_frozen, and a site that is neither active nor frozen answers 409 conflict. A site your API key can no longer reach answers 404.

A 503 service_unavailable with a scan_id member means the scan was created but the scan queue refused it: that scan is listed as failed, and your organisation's owner gets an email about it. A 503 without scan_id started nothing.

When the scan finishes, your organisation's owner gets the scan completed email if their notification setting "Manual scan completed" is on. For a site created through the API it is sent only if your organisation has also turned on emails about sites created through the API.

Starting scans has its own limits: 60 an hour for your organisation and 6 a day for a site. Only a request that created a scan counts toward them: the 202, and the 503 with scan_id. An idempotent replay does not count, and it returns the scan as it was when it started, without Location and Retry-After.

Needs the scans:write permission.

Path parameters

Start a cookie scan: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Request headers

Start a cookie scan: request headers
Name Type Description
Idempotency-Key string minimum length 1, maximum length 255 A value of your own that names this request, so that sending the request again after a timeout returns the first answer while it is stored, in place of doing the work again: the same key with the same request answers with the first answer and Idempotent-Replayed: true.

Example request

curl -X POST "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/scans" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

202 Accepted: the scan was created and waits for the scanner. The body is the scan object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Idempotent-Replayed, Location, Retry-After.

Errors

Read a scan

GET /v1/sites/{siteKey}/scans/{scanId}

Permission: scans:read.

Reads one scan of the site. On top of the scan object it carries the embedded services the scan recognised, which pages loaded the banner, the pages that failed, what the website kept the scanner from loading and what the scan's first pages set before any choice. These members are there in every status, empty or null until the scan ran to its end.

The two page lists hold at most 25 pages each, and the counts cover the whole scan. The page addresses come from the scanned website, as untrusted_fields names them. A scan that was deleted answers 404. The operation takes no query parameters.

Needs the scans:read permission.

Path parameters

Read a scan: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
scanId Required string format uuid The scan's id, the id of the scan object.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/scans/4a6f0c2e-9b1d-4c3a-8e5f-7d2b1a0c9e8f" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the scan object with the members below. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Read a scan: answer 200
Name Type Description
services array of objects The embedded services (videos, maps and similar iframes) the scan recognised, by name. Filled once the scan ran to its end (completed or completed_with_errors), an empty list before that.
services[].id string, one of: youtube, vimeo, dailymotion, google-maps, facebook, instagram, twitter, tiktok, linkedin, spotify, recaptcha, hubspot Kukie.io's name for the service. New names can be added.
services[].name string The service's display name.
services[].provider string or null The company that runs the service, or null when Kukie.io does not name one.
services[].category string or null The cookie category the service belongs to, for example marketing, or null.
services[].outcome string, one of: created, existing, no_category created: this scan added the service to your site. existing: not added, because your site already has it or an earlier scan added it. no_category: not added, because your site has no cookie category for it.
banner_coverage object or null Which scanned pages loaded your site's Kukie.io banner. Null before the scan ran to its end, when no page gave a usable reading, or when the coverage could not be read.
banner_coverage.pages_checked integer How many scanned pages gave a usable reading.
banner_coverage.pages_with_banner integer How many of them loaded the banner with this site's key.
banner_coverage.pages_without_banner integer How many of them did not, counted over the whole scan.
banner_coverage.pages_excluded integer How many pages without the banner are left out because your banner settings turn the banner off there (disabled_pages).
banner_coverage.pages_blocked_by_content_security_policy integer How many pages without the banner carry the script, but their own Content Security Policy stopped it from running.
banner_coverage.missing array of objects maximum items 25 The pages without the banner, at most 25.
banner_coverage.missing[].url string maximum length 300 The page's address: its scheme, host and path only, never its query string or fragment. It comes from the scanned website.
banner_coverage.missing[].another_sites_key boolean Whether the page loaded a Kukie.io banner with another site's key, which records consent for that other site.
banner_coverage.missing[].blocked_by_content_security_policy boolean Whether the page's own Content Security Policy stopped the banner script from running.
banner_coverage.missing_truncated boolean Whether more pages are without the banner than missing lists.
failed_pages array of objects maximum items 25 The pages the scanner could not scan, at most 25, in the order of their addresses. Filled for a scan with the status completed_with_errors, an empty list otherwise.
failed_pages[].url string maximum length 300 The page's address: its scheme, host and path only, never its query string or fragment. It comes from the scanned website.
failed_pages[].reason string Why the page failed, in Kukie.io's words (English). Its wording can change.
failed_pages_truncated boolean Whether more pages failed than failed_pages lists.
blocked_by_site_owner object or null What the website kept the scanner from loading. Null unless the scan crawled politely. A scan you start through the API crawls politely when no scan has found the Kukie.io script on the site's own website in the last 45 days: it identifies itself as CookieConsentScanner, obeys the site's robots.txt and loads one page at a time. Also null while such a scan has not started to crawl.
blocked_by_site_owner.robots_txt integer minimum 0, maximum 20000 How many distinct addresses the scan did not fetch because robots.txt disallows them for the scanner, or because robots.txt could not be read. At most 20,000.
blocked_by_site_owner.refused integer minimum 0 How many loaded pages answered the scanner with a status that refuses it (401, 403, 406, 429, 451, 503).
before_consent object or null What the scan's first pages set and loaded when the scanner loaded them again as a first-time visitor in the EU who has not made a choice in any cookie banner. Kukie.io loads at most the scan's first 20 pages this way, and only when this check is switched on, which it is not yet: until then every scan reads not_checked with no page planned. Null before the scan ran to its end, for a scan that failed, or when the check could not be read.
before_consent.status string, one of: not_checked, partial, checked not_checked when no page was planned or no planned page could be loaded again (never read it as "nothing found"), partial when some planned pages could not be loaded again, checked when every planned page was. The counts cover the pages checked.
before_consent.pages_planned integer minimum 0 How many pages the scanner was to load again.
before_consent.pages_checked integer minimum 0 How many of them it loaded again and read.
before_consent.pages_failed integer minimum 0 How many failed to load again, or answered with an error status (400 or more).
before_consent.pages_skipped integer minimum 0 How many were not loaded again, most often because the first load left too little time.
before_consent.pages_storage_not_read integer minimum 0 On how many of the pages checked the browser storage could not be read, so storage_keys_count does not cover them.
before_consent.cookies_count integer minimum 0 How many distinct cookies (by name and domain) the pages checked set before any choice.
before_consent.storage_keys_count integer minimum 0 How many distinct keys the pages checked wrote to local storage or session storage before any choice, including _cc_uid, which the Kukie.io banner writes to local storage when it loads (the visitor's id in your consent records).
before_consent.request_hosts_count integer minimum 0 How many distinct hosts the pages checked sent requests to before any choice, the site's own included.
before_consent.third_party_hosts_count integer minimum 0 How many of those hosts belong to other sites. Kukie.io's own hosts, which serve the banner, are not counted.
untrusted_fields array of strings, each item one of: banner_coverage.missing[].url, failed_pages[].url The members whose values come from the scanned website or from a visitor's browser, not from Kukie.io. Escape them before you show them anywhere.

Errors

List the cookies a scan found

GET /v1/sites/{siteKey}/scans/{scanId}/cookies

Permission: scans:read.

Lists the distinct cookies the scan found, one entry for each name, in the order of their names. It answers for a scan in any status: a waiting scan has none, and a running scan's list is partial and grows, so pages read while it runs can change. The list is complete once the scan's status is completed or completed_with_errors.

Every string in an entry comes from the scanned website, as untrusted_fields names them. A cursor into a running scan can stop working (400): start again from the first page. A scan that was deleted answers 404.

Needs the scans:read permission.

Path parameters

List the cookies a scan found: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
scanId Required string format uuid The scan's id, the id of the scan object.

Query parameters

List the cookies a scan found: query parameters
Name Type Description
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/scans/4a6f0c2e-9b1d-4c3a-8e5f-7d2b1a0c9e8f/cookies" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds scan_cookie objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List the cookies a scan found: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.
untrusted_fields array of strings, each item one of: data[].name, data[].domain, data[].category, data[].type, data[].duration The members whose values come from the scanned website or from a visitor's browser, not from Kukie.io. Escape them before you show them anywhere.

Errors

A site's consent records and consent statistics.

GET /v1/sites/{siteKey}/consent-records/{consentId}

Permission: consent:read.

Reads the site's consent record with this consent id, the id on a visitor's consent receipt. When the id was recorded more than once, the earliest record answers. An id that is unknown, or that belongs to another site, answers 404.

The consent id comes from the visitor's browser, and so do the action, the categories, the services and the banner version, as untrusted_fields names them: escape them before you show them. The operation takes no query parameters and works for a frozen site too.

Needs the consent:read permission.

Path parameters

Read a consent record: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.
consentId Required string format uuid The consent id on a visitor's consent receipt. The visitor's browser creates it, so treat it as an identifier of that visitor.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/consent-records/9e1c3b5a-7d2f-4a6b-8c0d-2e4f6a8b0c1d" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the consent_record object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

GET /v1/sites/{siteKey}/consent-stats

Permission: consent:read.

Reads the site's consent figures for a window of whole days in UTC. The series is daily for a window of up to 92 days and monthly beyond. advanced is null unless your plan has Advanced analytics and it is turned on for the site. Works for a frozen site too.

The figures of one window are kept for 60 seconds, so they change at most that often and a window that ends today lags by up to that long. Each call with a valid window for a site your API key can reach counts toward this operation's own limits, on top of the read limits: 10 calls a minute for a site and 20 a minute for your organisation. A call counts whatever it then answers, an answer from the cache included. A 404 and a 422 do not count.

A 503 service_unavailable means the figures took too long to compute: wait the seconds Retry-After gives (60), then try again with a shorter window.

Needs the consent:read permission.

Path parameters

Read a site's consent statistics: path parameters
Name Type Description
siteKey Required string format uuid The site's id, the site key that also appears in its embed script URL.

Query parameters

Read a site's consent statistics: query parameters
Name Type Description
from Required string format date The window's first day, YYYY-MM-DD. On or before to, no earlier than 1 year before to plus one day (so a window holds at most 365 or 366 days), and no earlier than 3 years before today.
to Required string format date The window's last day, YYYY-MM-DD, today or earlier. A missing date, or one that breaks a rule, is a 422 that names it.

Example request

curl "https://api.kukie.io/v1/sites/0b9d4f6e-2c1a-4e7b-9a53-6f1d2c3b4a5e/consent-stats?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the consent_stats object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Webhooks

Webhook endpoints: the addresses your organisation wants its events sent to, their signing secrets and a test event.

List webhook endpoints

GET /v1/webhook-endpoints

Permission: webhooks:read.

Returns your organisation's webhook endpoints, newest first, disabled ones included. An endpoint never shows its signing secret here.

Webhook endpoints and events belong to your whole organisation, so an API key limited to selected sites answers 403 insufficient_scope here.

Needs the webhooks:read permission.

Query parameters

List webhook endpoints: query parameters
Name Type Description
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds webhook_endpoint objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List webhook endpoints: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.

Errors

Add a webhook endpoint

POST /v1/webhook-endpoints

Permission: webhooks:write.

Adds an address that your organisation's events are sent to. The answer carries the endpoint's signing secret, this once: every delivery is signed with it, so store it where your receiver can read it.

url must be an https address on the public internet, at most 2,048 characters, on the standard port, with no user name, password or fragment. Write a domain name with characters outside ASCII in its xn-- form, and such characters in the path percent-encoded. An address on a private network or on Kukie.io's own domain is refused. The address is checked again each time an event is sent.

An organisation can have 10 webhook endpoints, disabled ones included. One more answers 422 validation_failed with the code limit_reached.

Kukie.io looks the address up when you create an endpoint or change its url. Your organisation can check one address or send one test event at a time, and Kukie.io checks only a few addresses and sends only a few test events at once for all customers. While another check or test of your organisation is running, or Kukie.io is at that limit, the answer is 429 concurrency_limited with Retry-After: 10 and nothing is written. A 503 service_unavailable wrote nothing either.

With an Idempotency-Key, a repeated request returns the same endpoint with secret set to null, because the secret is never stored for a replay.

Webhook endpoints and events belong to your whole organisation, so an API key limited to selected sites answers 403 insufficient_scope here.

Needs the webhooks:write permission.

Request headers

Add a webhook endpoint: request headers
Name Type Description
Idempotency-Key string minimum length 1, maximum length 255 A value of your own that names this request, so that sending the request again after a timeout returns the first answer while it is stored, in place of doing the work again: the same key with the same request answers with the first answer and Idempotent-Replayed: true.

Request body

A JSON object. The body is required.

Add a webhook endpoint: request body
Name Type Description
url Required string format uri, maximum length 2048 The address to send events to.
enabled_events Required array of strings, each item one of: scan.completed, scan.failed, site.created, site.deleted, site.installation_verified, report.ready, * minimum items 1 The event types to send, each once (scan.completed, scan.failed, site.created, site.deleted, site.installation_verified, report.ready), or ["*"] alone for every type.
description string or null maximum length 255 Your own note about the endpoint, or null.

Example request

curl -X POST "https://api.kukie.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/kukie","enabled_events":["site.created","scan.completed"]}'

Answers

201 Created. The body is the webhook_endpoint_with_secret object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Idempotent-Replayed, Location.

Errors

Get a webhook endpoint

GET /v1/webhook-endpoints/{endpointId}

Permission: webhooks:read.

Returns one webhook endpoint, without its signing secret.

Webhook endpoints and events belong to your whole organisation, so an API key limited to selected sites answers 403 insufficient_scope here.

Needs the webhooks:read permission.

Path parameters

Get a webhook endpoint: path parameters
Name Type Description
endpointId Required string pattern ^whk_[0-9A-Za-z]{26}$ The webhook endpoint's id, the id of the webhook endpoint object.

Example request

curl "https://api.kukie.io/v1/webhook-endpoints/whk_01jd2k8q3v7n5m4x6c9b0a1e2f" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the webhook_endpoint object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Change a webhook endpoint

PATCH /v1/webhook-endpoints/{endpointId}

Permission: webhooks:write.

Changes the members you send. A member you leave out stays as it is, and you can send back the whole object you read: its other members are ignored. When nothing changes, nothing is written.

url must be an https address on the public internet, at most 2,048 characters, on the standard port, with no user name, password or fragment. Write a domain name with characters outside ASCII in its xn-- form, and such characters in the path percent-encoded. An address on a private network or on Kukie.io's own domain is refused. The address is checked again each time an event is sent. Changing url keeps the signing secret.

Kukie.io looks the address up when you create an endpoint or change its url. Your organisation can check one address or send one test event at a time, and Kukie.io checks only a few addresses and sends only a few test events at once for all customers. While another check or test of your organisation is running, or Kukie.io is at that limit, the answer is 429 concurrency_limited with Retry-After: 10 and nothing is written. A 503 service_unavailable wrote nothing either. Sending the url the endpoint already has does not check it again.

Set status to disabled to stop deliveries to the endpoint: no event is sent to it while it is off, and what it still had waiting is cancelled the next time deliveries go out. If you switch it on again before that, those deliveries are still sent. Set status to enabled to switch a disabled endpoint on again, whoever switched it off. Events from the time it was off are not sent afterwards: read them with GET /v1/events.

Webhook endpoints and events belong to your whole organisation, so an API key limited to selected sites answers 403 insufficient_scope here.

Needs the webhooks:write permission.

Path parameters

Change a webhook endpoint: path parameters
Name Type Description
endpointId Required string pattern ^whk_[0-9A-Za-z]{26}$ The webhook endpoint's id, the id of the webhook endpoint object.

Request body

A JSON object. The body is optional.

Change a webhook endpoint: request body
Name Type Description
url string format uri, maximum length 2048 The address events are sent to, as you sent it. Treat it as a secret if its path holds a token.
enabled_events array of strings, each item one of: scan.completed, scan.failed, site.created, site.deleted, site.installation_verified, report.ready, * minimum items 1 The event types to send, each once (scan.completed, scan.failed, site.created, site.deleted, site.installation_verified, report.ready), or ["*"] alone for every type.
description string or null maximum length 255 Your own note about the endpoint, or null.
status string, one of: enabled, disabled disabled switches the endpoint off, enabled switches it on again.

Example request

curl -X PATCH "https://api.kukie.io/v1/webhook-endpoints/whk_01jd2k8q3v7n5m4x6c9b0a1e2f" \
  -H "Authorization: Bearer $KUKIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled_events":["*"]}'

Answers

200 OK. The body is the webhook_endpoint object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Delete a webhook endpoint

DELETE /v1/webhook-endpoints/{endpointId}

Permission: webhooks:write.

Deletes a webhook endpoint and the record of its deliveries. Nothing more is sent to it, apart from what may already be on its way when you delete it. Your organisation's events stay readable with GET /v1/events. You can delete an endpoint when your plan no longer includes the API; this is the only webhook operation that works then.

Webhook endpoints and events belong to your whole organisation, so an API key limited to selected sites answers 403 insufficient_scope here.

Needs the webhooks:write permission.

Path parameters

Delete a webhook endpoint: path parameters
Name Type Description
endpointId Required string pattern ^whk_[0-9A-Za-z]{26}$ The webhook endpoint's id, the id of the webhook endpoint object.

Example request

curl -X DELETE "https://api.kukie.io/v1/webhook-endpoints/whk_01jd2k8q3v7n5m4x6c9b0a1e2f" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

204 Done. The answer has no body. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Rotate a webhook endpoint's signing secret

POST /v1/webhook-endpoints/{endpointId}/rotate-secret

Permission: webhooks:write.

Makes a new signing secret for the endpoint and returns it, this once. For 24 hours every delivery is signed with both the new secret and the one it replaced, so your receiver can change over without refusing a delivery; after that only the new one signs. A second rotation inside that time keeps the secret it replaced, not the one before it.

The request takes no query parameters and no body members: send no body or {}. With an Idempotency-Key, a repeated request rotates nothing and returns the endpoint with secret set to null. If you lost the answer and rotate again, the secret your receiver still holds stops signing at once: the overlap then covers the secret you never received.

Webhook endpoints and events belong to your whole organisation, so an API key limited to selected sites answers 403 insufficient_scope here.

Needs the webhooks:write permission.

Path parameters

Rotate a webhook endpoint's signing secret: path parameters
Name Type Description
endpointId Required string pattern ^whk_[0-9A-Za-z]{26}$ The webhook endpoint's id, the id of the webhook endpoint object.

Request headers

Rotate a webhook endpoint's signing secret: request headers
Name Type Description
Idempotency-Key string minimum length 1, maximum length 255 A value of your own that names this request, so that sending the request again after a timeout returns the first answer while it is stored, in place of doing the work again: the same key with the same request answers with the first answer and Idempotent-Replayed: true.

Example request

curl -X POST "https://api.kukie.io/v1/webhook-endpoints/whk_01jd2k8q3v7n5m4x6c9b0a1e2f/rotate-secret" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the webhook_endpoint_with_secret object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Idempotent-Replayed.

Errors

Send a test event

POST /v1/webhook-endpoints/{endpointId}/test

Permission: webhooks:write.

Sends one webhook.test event to this endpoint, whatever its enabled_events, and answers with what happened. The request is signed like every delivery and waits up to 10 seconds for the endpoint. Every test that was sent answers 200: read delivered. A test is sent once and never again, and a failed test does not count against the endpoint.

A disabled endpoint answers 409 conflict: switch it on first. Your organisation can run one test or address check at a time; while another runs, or the API is running as many tests and address checks as it allows at once, the answer is 429 concurrency_limited with Retry-After: 10. A 503 service_unavailable delivered nothing.

Tests have their own limits: 5 a minute for an endpoint and 60 an hour for your organisation. A test counts once it was recorded, whatever the endpoint answered; a refusal before that (404, 409, 422, 429) and a replay do not.

The request takes no query parameters and no body members: send no body or {}.

Webhook endpoints and events belong to your whole organisation, so an API key limited to selected sites answers 403 insufficient_scope here.

Needs the webhooks:write permission.

Path parameters

Send a test event: path parameters
Name Type Description
endpointId Required string pattern ^whk_[0-9A-Za-z]{26}$ The webhook endpoint's id, the id of the webhook endpoint object.

Request headers

Send a test event: request headers
Name Type Description
Idempotency-Key string minimum length 1, maximum length 255 A value of your own that names this request, so that sending the request again after a timeout returns the first answer while it is stored, in place of doing the work again: the same key with the same request answers with the first answer and Idempotent-Replayed: true.

Example request

curl -X POST "https://api.kukie.io/v1/webhook-endpoints/whk_01jd2k8q3v7n5m4x6c9b0a1e2f/test" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the webhook_test object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Idempotent-Replayed.

Errors

Events

The events of your organisation, as a webhook delivery reports them, for the 30 days they are kept.

List events

GET /v1/events

Permission: webhooks:read.

Returns your organisation's events of the last 30 days, newest first, whether or not a webhook endpoint received them. Use it to catch up on what your endpoint missed. Events are kept for 30 days and are not listed after that.

Webhook endpoints and events belong to your whole organisation, so an API key limited to selected sites answers 403 insufficient_scope here.

Needs the webhooks:read permission.

Query parameters

List events: query parameters
Name Type Description
type string, one of: scan.completed, scan.failed, site.created, site.deleted, site.installation_verified, report.ready, webhook.test Only events of this type.
from string format date-time Only events from this time on, in UTC, written as 2026-11-18T10:20:30Z. A time more than 30 days ago is a 422.
to string format date-time Only events before this time, in UTC, written as 2026-11-18T10:20:30Z. It must be later than from.
limit integer default 25, minimum 1, maximum 100 How many items a page holds.
cursor string The next_cursor of the page before. A cursor works only with the key, the operation and the filters it was made for.

Example request

curl "https://api.kukie.io/v1/events" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is a list whose data holds event objects. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

List events: answer 200
Name Type Description
has_more boolean Whether more items follow this page.
next_cursor string or null Send it as cursor to read the next page. Null on the last page.

Errors

Get an event

GET /v1/events/{eventId}

Permission: webhooks:read.

Returns one event. An event older than 30 days answers 404 not_found.

Webhook endpoints and events belong to your whole organisation, so an API key limited to selected sites answers 403 insufficient_scope here.

Needs the webhooks:read permission.

Path parameters

Get an event: path parameters
Name Type Description
eventId Required string pattern ^evt_[0-9A-Za-z]{26}$ The event's id, the id of the event object and the webhook-id header of its deliveries.

Example request

curl "https://api.kukie.io/v1/events/evt_01jd2m4r6t8w0y2a4c6e8g0j2m" \
  -H "Authorization: Bearer $KUKIE_API_KEY"

Answers

200 OK. The body is the event object. Headers: Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

Objects

The objects the operations above return, in the order the OpenAPI document lists them.

api

The API's descriptor. Members can be added, never removed or renamed.

Members of the api object
Name Type Description
object always "api" The kind of object, always api.
version always "v1" The version of the API that answered.
documentation_url always "https://kukie.io/docs/api" format uri Where the API's documentation is.

account

The calling API key, its organisation, the plan's limits and features, the organisation's site counts and the general rate limits.

Members of the account object
Name Type Description
object always "account" The kind of object, always account.
organization object The organisation the API key belongs to.
organization.name string The organisation's name.
plan object The organisation's plan.
plan.name string The plan's name.
plan.api_access boolean Whether the plan includes the API. When it is false, every operation that needs an API key answers 403 plan_upgrade_required, apart from this one and DELETE /v1/webhook-endpoints/{endpointId}.
key object The API key that sent this request.
key.id string The key's id, starting key_.
key.name string The name the key was given when it was created.
key.last_four string The last four characters of the key, to tell keys apart.
key.scopes array of strings, each item one of: sites:read, sites:write, sites:delete, banner:read, banner:write, accessibility:read, accessibility:write, scans:read, scans:write, consent:read, webhooks:read, webhooks:write, reports:read The key's permissions, including those another permission implies. New permissions can be added.
key.site_mode string, one of: all, selected all when the key reaches every site of the organisation, selected when it reaches only the sites chosen for it.
key.expires_at string format date-time When the key expires, in UTC. A key that was rolled stops at the end of its grace period, which can be earlier.
limits object The limits of the organisation's plan, the same for every API key of the organisation. null means the plan sets no limit.
limits.max_sites integer or null The most sites the plan includes, or null for no limit.
limits.max_pages_per_scan integer or null The most pages one cookie scan reads. null means the plan sets no limit; a scan then stops at 10,000 pages.
limits.max_region_rules integer or null How many region rules, beside the Rest of World rule (default), a site can have switched on at once, or null for no limit. It is checked when a rule is created or switched on, and a rule that is off takes no place. A copy of settings counts differently: it takes the first rules in their order up to this number, whether they are on or off.
usage object The sites the API key reaches. For a key that reaches all sites these are the organisation's sites. For a key that reaches selected sites the counts cover those sites only, and say nothing about the organisation's other sites.
usage.sites integer minimum 0 How many sites the key reaches: every site of the organisation, or the sites selected for the key.
usage.frozen_sites integer minimum 0 How many of them are frozen because the organisation has more sites than its plan includes.
usage.can_create_site boolean Whether the plan's site limit lets you create a site now. Always false for a key that reaches selected sites, because such a key cannot create a site. Where the limit is shared with other organisations of the same owner, it can be false while sites is below max_sites.
features object The plan's features, each true or false. New features can be added.
features.custom_css boolean Whether your plan includes this feature.
features.scheduled_scans boolean Whether your plan includes this feature.
features.bulk_scan boolean Whether your plan includes this feature.
features.reports boolean Whether your plan includes this feature.
features.gcm boolean Whether your plan includes this feature.
features.gtm boolean Whether your plan includes this feature.
features.matomo boolean Whether your plan includes this feature.
features.ms_uet boolean Whether your plan includes this feature.
features.clarity_consent boolean Whether your plan includes this feature.
features.amazon_consent boolean Whether your plan includes this feature.
features.http_cookies boolean Whether your plan includes this feature.
features.site_settings_copy boolean Whether your plan includes copying one site's settings to other sites, as POST /v1/sites/{siteKey}/copy-settings does.
features.accessibility_widget boolean Whether your plan includes the accessibility widget. Without it, changes to the widget answer 403 plan_upgrade_required.
features.uptime_monitoring boolean Whether your plan includes this feature.
features.advanced_analytics boolean Whether your plan includes this feature.
features.branding_required boolean Whether your plan requires the banner to show Kukie.io branding. true is a restriction, not a feature.
features.api_access boolean Whether your plan includes the API, the same value as plan.api_access.
rate_limits object The general rate limits every API key has. Limits of single operations are in those operations' descriptions.
rate_limits.requests_per_minute object Requests a minute, of any kind.
rate_limits.requests_per_minute.key integer For this API key.
rate_limits.requests_per_minute.organization integer For all the organisation's keys together.
rate_limits.writes_per_minute object Requests a minute that change something (POST, PATCH, PUT and DELETE), counted within the limits above.
rate_limits.writes_per_minute.key integer For this API key.
rate_limits.writes_per_minute.organization integer For all the organisation's keys together.
rate_limits.concurrent_requests integer How many requests the organisation can have running at once.

usage_record

API traffic of one group: one day, one API key or one operation, as group_by says. Exactly one of date, key and operation is present.

Members of the usage_record object
Name Type Description
object always "usage_record" The kind of object, always usage_record.
date string format date With group_by=day: the day, in UTC.
key object or null With group_by=key: the API key, or null if the key no longer exists.
key.id string The key's id, starting key_.
key.name string The key's name.
key.last_four string The last four characters of the key.
key.revoked boolean Whether the key was revoked. An expired key, and a rolled key past its grace period, read false.
operation string or null With group_by=operation: the method and path, such as GET /v1/sites/{siteKey}, or null for an operation the API no longer has.
requests integer minimum 0 How many requests the group holds, answers of 429 included.
by_status object The requests by the class of their HTTP status.
by_status.2xx integer minimum 0 Requests answered with a 2xx status.
by_status.3xx integer minimum 0 Requests answered with a 3xx status.
by_status.4xx integer minimum 0 Requests answered with a 4xx status.
by_status.5xx integer minimum 0 Requests answered with a 5xx status.
average_duration_ms integer minimum 0 The time the server took to answer a request, on average, in whole milliseconds.
max_duration_ms integer minimum 0 The longest time the server took to answer one of the requests, in milliseconds.
response_bytes integer minimum 0 The size of all the answers' bodies together, in bytes.

settings_copy_result

What a settings copy did to one target site.

Members of the settings_copy_result object
Name Type Description
object always "settings_copy_result" The kind of object, always settings_copy_result.
site string format uuid The target site's id.
outcome string, one of: copied, skipped, failed copied when the settings were copied, skipped when the site was left as it was, failed when the copy to it failed and nothing of it was written.
code string, one of: site_frozen, not_found, copy_failed or null Why the site was skipped or failed: site_frozen (the site is frozen), not_found (the site left the API key's reach while the request ran) or copy_failed (an error at Kukie.io, so try again). null for a copied site.
warnings array of objects For a copied site: what was not copied, or what to check. Empty otherwise.
warnings[].code string, one of: region_rules_skipped, cookies_skipped, services_skipped, service_settings_kept, blocking_domains_skipped, settings_copy_notice, consent_mode_off_in_copied_settings, google_banner_text_incomplete, accessibility_widget_not_copied The warning's stable code. settings_copy_notice is a warning without a code of its own. New codes can be added.
warnings[].message string What happened, in English. It can name your own cookies, services, categories and regions.

settings_copy

The result of copying one site's settings to other sites.

Members of the settings_copy object
Name Type Description
object always "settings_copy" The kind of object, always settings_copy.
source string format uuid The id of the site the settings were copied from.
results array of settings_copy_result objects One result for each distinct target site, in the order you sent them.
totals object The counts of the whole copy.
totals.targets integer minimum 0 How many distinct target sites the request named.
totals.copied integer minimum 0 How many of them were copied to.
totals.skipped integer minimum 0 How many were skipped.
totals.failed integer minimum 0 How many failed.
totals.cookies_copied integer minimum 0 How many cookies were copied, over all the copied sites. 0 unless include_cookies was true.
totals.services_copied integer minimum 0 How many services were copied, over all the copied sites. 0 unless include_services was true.

site

A website of your organisation that runs the Kukie.io banner.

Members of the site object
Name Type Description
object always "site" Always site.
id string format uuid The site key, the one identifier of the site. Use it in the URL of every site operation.
domain string The site's domain name, lowercased, for example shop.example.com.
status string, one of: awaiting_setup, live, frozen_grace, frozen awaiting_setup until the banner is confirmed on the site, then live. frozen_grace is a frozen site in its grace period, frozen one whose grace period has ended or that has none. A site is frozen when your organisation has more sites than its plan includes.
external_id string or null Your own identifier for the site, or null when it has none.
metadata object Your own key and value strings for the site. {} when none are stored.
created_via string, one of: dashboard, api, demo How the site was created: in the dashboard, through the API, or as a demo site.
verified_at string or null format date-time When the banner was last confirmed on the site (ISO 8601, UTC), or null. A visitor's consent sent from the site's domain also sets it, so it is not proof that you control the domain.
last_consent_at string or null format date-time When the site last recorded a visitor's consent (ISO 8601, UTC), or null.
frozen_at string or null format date-time When the site was frozen (ISO 8601, UTC), or null.
created_at string or null format date-time When the site was created (ISO 8601, UTC).
embed object How to install the banner on the site.
embed.script_url string format uri The URL of the site's banner script.
embed.html string The script tag that installs the banner on the site's pages.

installation_check

The result of an installation check: whether the Kukie.io banner was found on the site.

Members of the installation_check object
Name Type Description
object always "installation_check" Always installation_check.
site_id string format uuid The id of the site that was checked.
installed boolean Whether the banner is confirmed on the site.
outcome string, one of: verified, blocked_target, connection_failed, http_error, challenge, gtm_pending, csp_blocked, not_found Why the check ended as it did: verified (installed), blocked_target (the domain does not resolve, or resolves to an address that is not public), connection_failed (the site could not be reached), http_error (the site answered with an error), challenge (a bot protection page stood in front of the site), gtm_pending (a Google Tag Manager container was found, but the Kukie.io tag in it could not be confirmed), csp_blocked (the page's Content Security Policy stops the banner) or not_found (the page has no banner script). New values can be added.
confirmed_by string, one of: scan, consents, google_tag_manager, page, none What confirmed the installation: a scan of the site, consents recorded from it, its Google Tag Manager container, the page itself, or none when it is not installed.
script_found boolean Whether a Kukie.io banner script was found on the page.
site_key_matches boolean Whether the script found carries this site's key.
google_tag_manager_found boolean Whether a Google Tag Manager container was found on the page.
bot_challenge_found boolean Whether a bot protection challenge was found in place of the page.
blocked_by_content_security_policy boolean Whether the page's Content Security Policy stops the banner from loading.
content_security_policy_fixes array of objects maximum items 10 Changes to the page's Content Security Policy that would let the banner load, at most 10. Empty when none are needed.
content_security_policy_fixes[].kind string, one of: script, style, connect What the change unblocks: the banner script, its styles, or its requests.
content_security_policy_fixes[].action string, one of: add, new, replace Add value to the directive, add the directive with value, or replace the directive with value.
content_security_policy_fixes[].directive string maximum length 60 The directive to change, for example script-src.
content_security_policy_fixes[].value string maximum length 300 The source or sources the action uses. Untrusted: escape it before you render it.
url_checked string or null maximum length 300 The address that was checked, without its query or fragment, or null. Untrusted: escape it before you render it.
message string or null maximum length 600 What went wrong, in English for a developer, or null. Untrusted: escape it before you render it.
untrusted_fields array of strings The fields whose values come from the checked site. Escape them before you render them.

banner_settings

A site's banner settings: the Banner Editor's settings with their stored values, the on or off switch, and read-only members. The values are what is stored; plan_limits says which of them your plan lets the banner use.

Members of the banner_settings object
Name Type Description
object always "banner_settings" Always banner_settings.
etag string The version tag of the settings, quotation marks included, the same value as the ETag header. Send it as If-Match with your next change.
config_version integer The version number of the settings. It rises with every saved change, including saves made in the dashboard or the WordPress plugin.
banner_enabled boolean Whether the banner is on for the site.
layout string, one of: popup, bar-bottom, bar-top, floating or null How the banner shows: a popup, a bar at the bottom or the top of the page, or a floating box.
position string, one of: center, bottom-left, bottom-center, bottom-right or null Where a floating banner sits on the page. Needed when layout is floating.
theme object The banner's colours, corner radii and button styles. Colours take a hex value or a var(--name) token of your page.
theme.primary_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.button_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.border_radius string or null Text. Null when not set.
theme.button_border_radius string or null Text. Null when not set.
theme.dark_primary_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_button_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_hover_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_accept_btn_hover_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.reject_btn_hover_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_reject_btn_hover_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.customize_btn_hover_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.dark_customize_btn_hover_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
theme.accept_btn_border_width string or null Text. Null when not set.
theme.reject_btn_border_width string or null Text. Null when not set.
theme.customize_btn_border_width string or null Text. Null when not set.
theme.accept_btn_bold boolean or null True or false. Null when not set.
theme.reject_btn_bold boolean or null True or false. Null when not set.
theme.customize_btn_bold boolean or null True or false. Null when not set.
color_source string, one of: custom, inherit or null custom uses the theme's primary colour; inherit takes the primary colour from the visitor's page where the page declares one.
font_source string, one of: system, inherit or null system uses the device's system font; inherit uses the font of the visitor's page.
auto_dark_mode boolean or null Whether the banner uses dark colours when the visitor's device is set to a dark appearance.
dark_mode_source string, one of: auto, custom or null auto picks the dark colours for you; custom uses the theme's dark_ colours.
custom_css string or null Your own CSS for the banner. Used only on a plan with custom CSS.
show_branding boolean or null Whether the banner shows the Kukie.io branding. It stays on unless your plan includes removing it.
show_overlay boolean or null Whether a popup banner darkens the page behind it.
disabled_pages array of strings or null Page address patterns where the banner is not shown.
auto_block_scripts boolean or null Whether known tracking scripts are held until the visitor consents.
respect_dnt boolean or null Whether the banner honours the browser's Do Not Track signal.
respect_gpc boolean or null Whether the banner honours the browser's Global Privacy Control signal.
gcm_v2_enabled boolean or null Whether the banner sends Google Consent Mode signals.
gcm_url_passthrough boolean or null Whether Google Consent Mode passes ad click information through page addresses.
gtm_enabled boolean or null Whether the banner loads your Google Tag Manager container.
gtm_container_id string or null The Google Tag Manager container to load, such as GTM-ABC123.
gtm_before_consent boolean or null Whether the container loads before the visitor makes a choice, instead of after it.
matomo_enabled boolean or null Whether the banner tells your Matomo tracker about the visitor's choice.
matomo_site_id string or null Your Matomo site id, digits only.
matomo_tracker_url string or null The address of your Matomo tracker.
ms_uet_enabled boolean or null Whether the banner sends Microsoft UET consent signals.
clarity_consent_enabled boolean or null Whether the banner sends Microsoft Clarity consent signals.
amazon_consent_enabled boolean or null Whether the banner sends Amazon consent signals.
iframe_blocking_enabled boolean or null Whether embedded content from known services is held until the visitor consents.
blocked_iframe_services array of strings or null, each item one of: youtube, vimeo, dailymotion, google-maps, facebook, instagram, twitter, tiktok, linkedin, spotify, recaptcha, hubspot The embedded services held until consent.
iframe_placeholder object How the placeholder shown in place of held embedded content looks. Its custom_css is used only on a plan with custom CSS.
iframe_placeholder.inherit_layout boolean or null True or false. Null when not set.
iframe_placeholder.bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.bg_transparent boolean or null True or false. Null when not set.
iframe_placeholder.text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.border_width string or null Text. Null when not set.
iframe_placeholder.border_radius string or null Text. Null when not set.
iframe_placeholder.min_height string or null Text. Null when not set.
iframe_placeholder.accept_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.accept_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.accept_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.accept_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.accept_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.prefs_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
iframe_placeholder.button_border_radius string or null Text. Null when not set.
iframe_placeholder.show_icon boolean or null True or false. Null when not set.
iframe_placeholder.show_service_name boolean or null True or false. Null when not set.
iframe_placeholder.show_preferences_button boolean or null True or false. Null when not set.
iframe_placeholder.custom_css string or null Text. Null when not set.
preferences_modal object How the preferences window looks and what it shows. Its texts map holds a title, a description and a privacy request link text for each language. Its icon and logo settings are used only on a plan that includes removing the branding.
preferences_modal.button_layout string, one of: stacked, row or null One of the listed values. Null when not set.
preferences_modal.button_order array of strings or null, each item one of: save, reject, accept Text. Null when not set.
preferences_modal.max_width string or null Text. Null when not set.
preferences_modal.show_policy_links boolean or null True or false. Null when not set.
preferences_modal.show_privacy_request_link boolean or null True or false. Null when not set.
preferences_modal.show_consent_id boolean or null True or false. Null when not set.
preferences_modal.show_overlay boolean or null True or false. Null when not set.
preferences_modal.custom_button_colors boolean or null True or false. Null when not set.
preferences_modal.show_icon boolean or null True or false. Null when not set.
preferences_modal.logo_url string or null Text. Null when not set.
preferences_modal.logo_max_width integer or null A whole number. Null when not set.
preferences_modal.logo_border_radius integer or null A whole number. Null when not set.
preferences_modal.texts object or null Text. Null when not set.
preferences_modal.texts.*.title string or null Text. Null when not set.
preferences_modal.texts.*.description string or null Text. Null when not set.
preferences_modal.texts.*.privacy_request string or null Text. Null when not set.
preferences_modal.accept_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.accept_btn_hover_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.reject_btn_hover_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_hover_bg_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_hover_text_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
preferences_modal.save_btn_hover_border_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
reload_on_consent boolean or null Whether the page reloads after the visitor makes a choice.
revisit_button object The button that lets a visitor open the banner again after a choice.
revisit_button.enabled boolean or null True or false. Null when not set.
revisit_button.position string, one of: bottom_left, bottom_right, top_left, top_right or null One of the listed values. Null when not set.
revisit_button.style string, one of: icon, pill, tab or null One of the listed values. Null when not set.
revisit_button.icon string, one of: cookie, shield, settings, fingerprint, lock, sliders or null One of the listed values. Null when not set.
revisit_button.text string or null Text. Null when not set.
revisit_button.color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
revisit_button.icon_color string or null A colour: a hex value such as #1f2937, or a var(--name) token of your page with an optional hex fallback. Null when not set.
revisit_button.offset_x integer or null A whole number. Null when not set.
revisit_button.offset_y integer or null A whole number. Null when not set.
auto_translate boolean or null Whether the banner shows in the visitor's language from the built-in translations.
default_language string or null The language the banner falls back to.
enabled_languages array of strings or null The languages the banner may show in.
logo_url string or null The address of a logo shown beside the banner title. Used only on a plan with a custom logo.
logo_max_width integer or null The logo's largest width, in pixels.
logo_border_radius integer or null The logo's corner radius, in pixels.
show_reject_all boolean or null Whether the banner shows the Reject all button.
show_customize boolean or null Whether the banner shows the button that opens the preferences.
show_close_button boolean or null Whether the banner shows a close button.
button_order array of strings or null, each item one of: customize, reject, accept The order of the banner's three buttons, each listed once. Null for the default order.
show_cookie_policy_link boolean or null Whether the banner shows the cookie policy link.
show_privacy_policy_link boolean or null Whether the banner shows the privacy policy link.
show_policy_links_in_banner boolean or null Whether the policy links show in the banner itself. When false they show only in the preferences window.
show_title_icon boolean or null Whether the banner shows the icon or logo beside its title. Used only on a plan that includes removing the branding.
google_consent_text_applied boolean Whether Google's banner text was applied from the Banner Editor.
plan_limits object What your plan lets the banner use. A stored value the plan does not include is kept but not used.
plan_limits.can_remove_branding boolean Whether the Kukie.io branding can be turned off, and the title icon and the preferences window's icon and logo settings are used.
plan_limits.can_use_custom_css boolean Whether custom_css and iframe_placeholder.custom_css are used.
plan_limits.can_use_logo boolean Whether logo_url is used.

banner_text

One language's banner texts.

Members of the banner_text object
Name Type Description
object always "banner_text" Always banner_text.
locale string The language code, such as de or pt-br.
is_default boolean Whether this is the site's default language. A site has one.
etag string The version tag of this language's texts, quotation marks included. It changes when these texts change and when the site's default language moves. Send it as If-Match with your next change.
title string or null The banner's title. Null when the language has no text of its own for it; the banner then shows its built-in text.
description string or null The banner's main text. It can hold a link and simple formatting, which are cleaned when the banner is built. Null when the language has no text of its own for it; the banner then shows its built-in text.
accept_all_btn string or null The label of the button that accepts all cookies. Null when the language has no text of its own for it; the banner then shows its built-in text.
reject_all_btn string or null The label of the button that rejects all cookies. Null when the language has no text of its own for it; the banner then shows its built-in text.
customize_btn string or null The label of the button that opens the preferences. Null when the language has no text of its own for it; the banner then shows its built-in text.
save_preferences_btn string or null The label of the button that saves the visitor's choices in the preferences. Null when the language has no text of its own for it; the banner then shows its built-in text.
privacy_policy_text string or null The words of the privacy policy link. Null when the language has no text of its own for it; the banner then shows its built-in text.
privacy_policy_url string or null The address the privacy policy link opens. Null when the language has no text of its own for it; the banner then shows its built-in text.
cookie_policy_text string or null The words of the cookie policy link. Null when the language has no text of its own for it; the banner then shows its built-in text.
cookie_policy_url string or null The address the cookie policy link opens. Null when the language has no text of its own for it; the banner then shows its built-in text.
cookie_provider_label string or null The label for a cookie's provider in the cookie details. Null when the language has no text of its own for it; the banner then shows its built-in text.
cookie_duration_label string or null The label for how long a cookie lasts in the cookie details. Null when the language has no text of its own for it; the banner then shows its built-in text.
cookie_description_label string or null The label for a cookie's description in the cookie details. Null when the language has no text of its own for it; the banner then shows its built-in text.
no_cookies_detected_text string or null The text shown where a category lists no cookies. Null when the language has no text of its own for it; the banner then shows its built-in text.
category_texts object The name and description of each cookie category in this language, by the category's slug. {} when there are none.
category_texts.*.name string The category's name. Empty when not set.
category_texts.*.description string The category's description. Empty when not set.

banner_warning

Something a write did not do as sent, or that you should check. Read code, which never changes; message is a sentence for a person.

Members of the banner_warning object
Name Type Description
code string, one of: description_falls_back_to_built_in_text, google_privacy_link_missing, google_ads_sentence_missing, links_to_other_websites, branding_css_removed, branding_not_in_plan, title_icon_not_in_plan, logo_not_in_plan, custom_css_not_in_plan, consent_mode_off, google_banner_text_incomplete The stable name of the warning. New codes can be added.
message string What the warning means, in English.

region_rule

A site's consent settings for visitors in one region. A visitor gets the rule for their region, then the rule for its parent region (eu for eu-de), then the Rest of World rule (default). The site's banner settings can still hide a button a rule shows.

Members of the region_rule object
Name Type Description
object always "region_rule" Always region_rule.
region_code string The rule's id: its region code, unique for each site, for example eu, us-ca or default (the Rest of World rule every site keeps). It never changes.
etag string The rule's version, quotation marks included. Send it as If-Match with a PATCH or DELETE of this rule.
consent_model string, one of: opt_in, opt_out, notice_only, hidden How the banner asks for consent in this region: opt_in keeps cookies and tags waiting for the visitor's choice, opt_out and notice_only start with consent granted before the visitor chooses, and hidden shows no banner and starts with consent granted.
show_reject_all boolean Whether the banner shows Reject all in this region.
show_preferences boolean Whether the banner shows Manage preferences in this region.
show_accept_all boolean Whether the banner shows Accept all in this region.
cookie_wall_enabled boolean Whether an opt-in banner covers the page until the visitor chooses. It needs Accept all or Manage preferences, so visitors have a way past it, and has no effect with another consent model.
dismiss_on_scroll boolean For a notice_only banner: whether the notice closes with implied consent once the visitor scrolls further than dismiss_on_scroll_distance pixels without using it.
dismiss_on_scroll_distance integer How far the visitor scrolls, in pixels, before the notice closes, from 50 to 1000.
dismiss_on_timeout boolean For a notice_only banner: whether the notice closes with implied consent after dismiss_timeout_seconds seconds without being used.
dismiss_timeout_seconds integer or null How many seconds the notice stays before it closes, from 5 to 300, or null when no time is set.
consent_duration_days integer How many days a visitor's choice is kept before the banner asks again, from 1 to 730.
reconsent_on_change boolean Whether visitors are asked again after the banner's configuration changes.
show_dnsmpi_link boolean Whether links on the site that carry the data-cc-dnsmpi attribute open the Do Not Sell or Share dialog in this region.
data_selling_opt_out boolean Stored with the rule. The banner does not read it.
is_active boolean Whether the rule is in use. A rule that is off is kept, and its visitors get the rule of the parent region or the Rest of World rule.
sort_order integer The rule's place in the list, lowest first. It does not change which rule a visitor gets.
quota_locked_at string or null format date-time When a plan change switched the rule off because the plan's limit on active custom rules was passed (ISO 8601, UTC), or null. Switching the rule on again clears it.

A cookie the site's banner lists.

Members of the cookie object
Name Type Description
object always "cookie" Always cookie.
id string pattern ^ck_[0-9a-f]{32}$ The cookie's id: ck_ and 32 hexadecimal characters. It stays the same for the cookie, so you can store it, but it can change once if Kukie.io rotates its encryption key: then list the cookies again.
name string maximum length 120 The cookie's name. Untrusted text.
domain string or null maximum length 253 The domain the cookie is set for, or null. Untrusted text.
path string or null maximum length 255 The path the cookie is set for, or null. Untrusted text.
category string or null The slug of the site's category the cookie is in, or null when it is in none of them.
provider string or null maximum length 120 Who sets the cookie, or null. Untrusted text.
duration string or null maximum length 60 How long the cookie lasts, as text, or null. Untrusted text.
description string or null maximum length 400 What the cookie is for, or null. Untrusted text.
type string or null maximum length 20 What kind of storage the cookie is, for example http, or null. Untrusted text.
found_by_scan boolean Whether a scan found the cookie. False for a cookie a person added.
recognised boolean Whether Kukie.io matched the cookie to a cookie it knows.
manually_categorised boolean Whether the cookie was put in its category by hand, through the dashboard or this API, so a later scan keeps it there.
needs_review boolean Whether the cookie is waiting for a category: found by a scan, not recognised, not categorised by hand, and still in the functional category.
last_seen_at string or null format date-time When a scan last found the cookie (ISO 8601, UTC), or null.

One of the cookie categories a site's banner offers.

Members of the cookie_category object
Name Type Description
object always "cookie_category" Always cookie_category.
slug string The category's id, unique for each site, for example functional.
name string maximum length 80 The category's name. Untrusted text.
description string or null maximum length 500 What the category is for, or null. Untrusted text.
required boolean Whether the category is always on, so visitors cannot switch it off.

The result of moving cookies into a category.

Members of the cookie_categorisation object
Name Type Description
object always "cookie_categorisation" Always cookie_categorisation.
category cookie_category object
cookies array of cookie objects The cookies you sent, as they now are, in the order the cookie list uses.
untrusted_fields array of strings, each item one of: category.name, category.description, cookies[].name, cookies[].domain, cookies[].path, cookies[].provider, cookies[].duration, cookies[].description, cookies[].type The members whose text comes from a scanned site or a person, as paths such as data[].name. That text is cleaned of control and invisible characters and cut to a length, but markup is left as it is: escape these values before you render them.

accessibility_widget

A site's accessibility widget settings.

Members of the accessibility_widget object
Name Type Description
object always "accessibility_widget" The object's type.
etag string The version of the widget's settings. Send it as If-Match with your next change.
available boolean Whether your organisation's plan includes the widget.
active boolean Whether the widget is shown on the site: available and enabled are both true.
enabled boolean The stored switch. The widget is shown only when active is true.
position string, one of: bottom-right, bottom-left The bottom corner of the page the widget's button sits in.
color string or null The widget's colour, as #rrggbb. Null uses the banner's own colour.
hidden_modules array of strings, each item one of: textSize, spacing, lineHeight, dyslexia, bold, contrast, sat, align, scale, links, titles, motion, images, sound, cursor, guide, tts, profiles, structure, language maximum items 20 The panel's tools that are hidden. A tool not listed is shown, so a tool added to the widget later appears without a change here.
hide_mobile boolean Whether the widget is hidden on screens up to 767 pixels wide.
size integer, one of: 44, 52, 60 The diameter of the widget's button, in pixels.
statement_enabled boolean Whether the panel shows a link to an accessibility statement.
statement_url string or null format uri The address that link opens. Null uses the site's published accessibility statement, when it has one. With neither, the panel shows no link.
languages array of strings, each item one of: ar, az, be, bg, bn, bs, ca, cs, cy, da, de, el, en, es-ar, es-mx, es, et, eu, fa, fi, fr, ga, gl, he, hi, hr, ht, hu, hy, id, is, it, ja, ka, kk, km, ko, lb, lt, lv, mi, mk, mn, ms, mt, my, ne, nl, no, pl, pt-br, pt, qu, ro, ru, si, sk, sl, sm, sq, sr, sv, th, tl, tr, uk, ur, uz, vi, zh-tw, zh The languages the widget's panel can be shown in, with English always added. An empty list means the banner's languages and English.
default_language string, one of: ar, az, be, bg, bn, bs, ca, cs, cy, da, de, el, en, es-ar, es-mx, es, et, eu, fa, fi, fr, ga, gl, he, hi, hr, ht, hu, hy, id, is, it, ja, ka, kk, km, ko, lb, lt, lv, mi, mk, mn, ms, mt, my, ne, nl, no, pl, pt-br, pt, qu, ro, ru, si, sk, sl, sm, sq, sr, sv, th, tl, tr, uk, ur, uz, vi, zh-tw, zh or null The language the panel opens in. Null lets the widget pick the visitor's language.

accessibility_widget_text

The site's own texts for the widget's panel in one language.

Members of the accessibility_widget_text object
Name Type Description
object always "accessibility_widget_text" The object's type.
locale string The language code, such as de or pt-br.
etag string The version of this language's overrides. A language without overrides has one too. Send it as If-Match with your next change.
strings object The site's overrides, by text key, as they are stored. {} when the language has none. A key left out uses the shipped text. Escape the values before you render them.
defaults object The shipped texts of this language, by text key, never merged with the overrides. Only with include=defaults.

scan

A cookie scan of a site. The single scan read adds more members.

Members of the scan object
Name Type Description
object always "scan"
id string format uuid The scan's id.
status string, one of: pending, running, completed, completed_with_errors, failed pending while it waits for the scanner, running while it scans, completed or completed_with_errors (some pages failed) once it ran to its end, and failed when it could not finish.
trigger string, one of: api, manual, scheduled Who started the scan: api for a scan started through this API, manual for one started from the dashboard, the WordPress plugin or the AI connector, and scheduled for a scheduled scan.
pages_scanned integer minimum 0 How many pages the scan has scanned so far.
total_pages integer or null How many pages the scan found to scan, or null until it has looked for them.
pages_limit integer or null minimum 1 The most pages your plan let this scan load when it started. Null when your plan sets no page limit: the scan then stops at 10,000 pages.
cookies_found integer minimum 0 How many cookies the scan found.
new_cookies integer minimum 0 How many of them are new to the site.
banner_missing_everywhere boolean Whether no scanned page loaded the site's Kukie.io banner.
message string or null Why the scan failed or finished with errors, in Kukie.io's words (English), or null. For a scan in which some pages failed it gives the count, such as 3 of 40 pages failed., and never a page address: the pages are in failed_pages of the single scan. Its wording can change, so read status.
queue_position integer or null minimum 1 While the scan is pending, its place among all scans waiting on Kukie.io, 1 being next. Null in every other status.
created_at string or null format date-time When the scan was created, in UTC.
started_at string or null format date-time When the scan started to run, in UTC, or null until it does.
completed_at string or null format date-time When the scan ended, in UTC, or null until it does.

One distinct cookie name a scan found, however many pages set it. Where pages differ, each other member holds the smallest value any page gave. Every string comes from the scanned website.

Members of the scan_cookie object
Name Type Description
object always "scan_cookie"
name string maximum length 120 The cookie's name, at most 120 characters.
domain string or null maximum length 253 The domain the cookie was set for, or null.
category string or null maximum length 40 The slug of the cookie category Kukie.io matched the cookie to, or null when it matched none.
type string or null maximum length 20 How the value was stored, for example http, js, local_storage or session_storage.
duration string or null maximum length 60 How long the cookie lasts, as the scanner recorded it, or null.
new boolean Whether the site's previous completed scan did not find this name. Always false when the site has no earlier completed scan.

One consent record: the choice a visitor made on the site's banner.

Members of the consent_record object
Name Type Description
object always "consent_record"
consent_id string format uuid The consent id, in lower case.
action string maximum length 40 The choice recorded, for example accept_all, reject_all or custom, at most 40 characters.
categories_accepted array of strings maximum items 30, each item: maximum length 64 The slugs of the cookie categories the visitor accepted, at most 30 of up to 64 characters each.
services_accepted array of strings or null maximum items 100, each item: maximum length 64 The slugs of the services the visitor accepted, at most 100, or null when the record holds none (a site that asks by category, or an older banner).
created_at string or null format date-time When the choice was recorded, in UTC.
country_code string or null maximum length 8 The country the choice was made from, as a country code, or null when it is not known.
banner_version integer or null The banner version the visitor's browser reported, or null.
untrusted_fields array of strings, each item one of: action, categories_accepted[], services_accepted[], banner_version The members whose values come from the scanned website or from a visitor's browser, not from Kukie.io. Escape them before you show them anywhere.

A site's consent figures for a window of days: counts and rates only, never a record or anything about one visitor.

Members of the consent_stats object
Name Type Description
object always "consent_stats"
site_id string format uuid The site's id.
from string format date The window's first day, as you sent it.
to string format date The window's last day, as you sent it.
totals object The choices recorded in the window.
totals.choices integer All choices recorded. Each counts in exactly one of accept_all, reject_all and custom.
totals.accept_all integer Choices recorded with the action accept_all, implied.
totals.reject_all integer Choices recorded with the action reject_all, opt_out.
totals.custom integer Choices recorded with the action custom, update, accept_category.
totals.accept_rate number accept_all as a percentage of all choices, to one decimal place. 0 without choices.
totals.reject_rate number reject_all as a percentage of all choices, to one decimal place. 0 without choices.
totals.custom_rate number custom as a percentage of all choices, to one decimal place. 0 without choices.
series_granularity string, one of: day, month day for a window of up to 92 days, month for a longer one.
series array of objects One point for each day or month of the window, oldest first.
series[].period string The day (YYYY-MM-DD) or the month (YYYY-MM). A month holds only the days of it inside the window.
series[].total integer All choices recorded in the period.
series[].accept_all integer Choices counted in totals.accept_all.
series[].reject_all integer Choices counted in totals.reject_all.
series[].custom integer Choices counted in totals.custom.
accepted_by_category object For each of the site's own cookie categories, by slug, how many choices accepted it.
by_country array of objects maximum items 20 The 20 countries with the most choices over the days by_country_window names, most first. Choices with no known country are left out.
by_country[].country string maximum length 8 The country code.
by_country[].total integer All choices from that country.
by_country[].accepted integer Its choices counted in totals.accept_all.
by_country[].rejected integer Its choices counted in totals.reject_all.
by_country[].custom integer Its choices counted in totals.custom.
by_country_window object The days by_country covers. Today that is always the whole window, but read it rather than assume so.
by_country_window.from string format date The first day.
by_country_window.to string format date The last day.
advanced object or null The Advanced analytics figures for the window. Null unless your plan has Advanced analytics and it is turned on for the site.
advanced.collecting_since string or null format date The day Advanced analytics was turned on for the site, or null when it is not known.
advanced.incomplete boolean Whether more first choices than banner displays were counted in the window, so the display count is known to be incomplete.
advanced.kpis object The headline figures. Rates are percentages to one decimal place.
advanced.kpis.displays object How many times the banner was shown.
advanced.kpis.displays.value number or null The figure for the window, or null without a base to compute it from.
advanced.kpis.displays.previous number or null The same figure for the period of equal length that ends the day before from, or null when that period was not collected in full.
advanced.kpis.displays.delta number or null The change against previous: percentage points for a rate, percent per day for displays. Null when there is nothing to compare.
advanced.kpis.interaction_rate object First choices as a percentage of displays.
advanced.kpis.interaction_rate.value number or null The figure for the window, or null without a base to compute it from.
advanced.kpis.interaction_rate.previous number or null The same figure for the period of equal length that ends the day before from, or null when that period was not collected in full.
advanced.kpis.interaction_rate.delta number or null The change against previous: percentage points for a rate, percent per day for displays. Null when there is nothing to compare.
advanced.kpis.ignore_rate object 100 minus the interaction rate.
advanced.kpis.ignore_rate.value number or null The figure for the window, or null without a base to compute it from.
advanced.kpis.ignore_rate.previous number or null The same figure for the period of equal length that ends the day before from, or null when that period was not collected in full.
advanced.kpis.ignore_rate.delta number or null The change against previous: percentage points for a rate, percent per day for displays. Null when there is nothing to compare.
advanced.kpis.accept_rate object First choices that accepted all, as a percentage of first choices.
advanced.kpis.accept_rate.value number or null The figure for the window, or null without a base to compute it from.
advanced.kpis.accept_rate.previous number or null The same figure for the period of equal length that ends the day before from, or null when that period was not collected in full.
advanced.kpis.accept_rate.delta number or null The change against previous: percentage points for a rate, percent per day for displays. Null when there is nothing to compare.
advanced.kpis.consent_rate object First choices that granted consent, as a percentage of displays.
advanced.kpis.consent_rate.value number or null The figure for the window, or null without a base to compute it from.
advanced.kpis.consent_rate.previous number or null The same figure for the period of equal length that ends the day before from, or null when that period was not collected in full.
advanced.kpis.consent_rate.delta number or null The change against previous: percentage points for a rate, percent per day for displays. Null when there is nothing to compare.
advanced.layers array of objects The choices made with the buttons of each part of the banner.
advanced.layers[].key string The part of the banner: banner (the first layer), modal (the preferences window) or wall.
advanced.layers[].choices integer All choices made there.
advanced.layers[].accept_all integer Accept all.
advanced.layers[].reject_all integer Reject all.
advanced.layers[].save integer Saved choices.
advanced.layers[].close integer Closed without a choice.
advanced.returning object Choices of visitors who had chosen before.
advanced.returning.choices integer All choices counted in the window.
advanced.returning.revisits integer Choices of returning visitors.
advanced.returning.withdrawals integer Choices that withdrew consent given before.

webhook_endpoint

An address your organisation wants its events sent to. The signing secret is not part of it.

Members of the webhook_endpoint object
Name Type Description
object always "webhook_endpoint" The kind of object, always webhook_endpoint.
id string pattern ^whk_[0-9a-z]{26}$ The endpoint's id.
url string format uri, maximum length 2048 The address events are sent to, as you sent it. Treat it as a secret if its path holds a token.
description string or null maximum length 255 Your own note about the endpoint, or null.
enabled_events array of strings, each item one of: scan.completed, scan.failed, site.created, site.deleted, site.installation_verified, report.ready, * minimum items 1 The event types the endpoint receives, or ["*"] for every type, types added later included.
status string, one of: enabled, disabled enabled while events are sent to it, disabled once you or Kukie.io switched it off.
disabled_reason string, one of: manual, gone, sustained_failure or null Why a disabled endpoint is off: manual (you switched it off), gone (it answered 410) or sustained_failure (every attempt failed for about three days). Null while it is enabled. New reasons can be added.
disabled_at string or null format date-time When the endpoint was switched off, or null while it is enabled.
last_success_at string or null format date-time When the endpoint last answered a delivery with a 2xx status, or null when it never has.
created_at string or null format date-time When the endpoint was added.

webhook_endpoint_with_secret

A webhook endpoint with its signing secret, as creating an endpoint and rotating its secret return it.

Members of the webhook_endpoint_with_secret object
Name Type Description
object always "webhook_endpoint" The kind of object, always webhook_endpoint.
id string pattern ^whk_[0-9a-z]{26}$ The endpoint's id.
url string format uri, maximum length 2048 The address events are sent to, as you sent it. Treat it as a secret if its path holds a token.
description string or null maximum length 255 Your own note about the endpoint, or null.
enabled_events array of strings, each item one of: scan.completed, scan.failed, site.created, site.deleted, site.installation_verified, report.ready, * minimum items 1 The event types the endpoint receives, or ["*"] for every type, types added later included.
status string, one of: enabled, disabled enabled while events are sent to it, disabled once you or Kukie.io switched it off.
disabled_reason string, one of: manual, gone, sustained_failure or null Why a disabled endpoint is off: manual (you switched it off), gone (it answered 410) or sustained_failure (every attempt failed for about three days). Null while it is enabled. New reasons can be added.
disabled_at string or null format date-time When the endpoint was switched off, or null while it is enabled.
last_success_at string or null format date-time When the endpoint last answered a delivery with a 2xx status, or null when it never has.
created_at string or null format date-time When the endpoint was added.
secret string or null The endpoint's signing secret. It starts with whsec_. It is returned here once and never again, so store it now. Null in a replayed answer (the same Idempotency-Key again): rotate the secret if you lost the first answer.

webhook_test

What happened to a test event.

Members of the webhook_test object
Name Type Description
object always "webhook_test" The kind of object, always webhook_test.
endpoint_id string The endpoint the test was sent to.
event_id string The webhook.test event that was sent. You can read it with GET /v1/events/{eventId}.
delivered boolean Whether the test was delivered: the endpoint answered with a 2xx status. An answer with a body larger than 65,536 bytes counts as a failure.
status_code integer or null The HTTP status the endpoint answered with. Null when no answer came, and for a redirect or an answer that was too large.
duration_ms integer or null How long the attempt took, in milliseconds, name lookup included. For an address that was refused before any request it is the time until the refusal, which can be 0. Null when no attempt was made.
failure string or null Null when the test was delivered. Otherwise why it was not: http_ and the status for an answer outside 2xx, redirect (a redirect is never followed), oversized (the answer was too large), or a word for a request that got no answer, such as timeout, dns, connect, tls or blocked (the address is not allowed). New values can be added.

event

Something that happened in your organisation. It has the same members as the body of the webhook delivery that reports it.

Members of the event object
Name Type Description
id string pattern ^evt_[0-9a-z]{26}$ The event's id. A delivery of the event carries it in its webhook-id header, and a delivery sent again carries the same id.
object always "event" The kind of object, always event.
type string, one of: scan.completed, scan.failed, site.created, site.deleted, site.installation_verified, report.ready, webhook.test What happened. New types can be added. report.ready says that a scan report is ready: its data holds the site's and the scan's ids, the report's schema_version, content_hash and built_at, pdf.status, and in links the addresses of the JSON report and the PDF. Scan reports are not switched on yet, so no report.ready event is sent until Kukie.io announces them in the API changelog.
timestamp string format date-time When it happened.
api_version always "v1" The version of the API the event's data is written for.
data object What the event is about: the ids of the site or scan, and a few facts about it. It never holds data about your websites' visitors. Its members depend on type.

Errors

Every error body has these members. Each code has a page of its own, the address in the body's type.

Members of an error body
Name Type Description
type string format uri A page about this error: https://kukie.io/docs/api/errors/ followed by the code.
title string A short name for the error.
status integer The HTTP status of the answer.
detail string What happened and what to do about it.
code string, one of: bad_request, unauthenticated, forbidden, insufficient_scope, plan_upgrade_required, concurrency_limited, not_found, method_not_allowed, conflict, precondition_failed, payload_too_large, credential_in_query, validation_failed, idempotency_key_missing, idempotency_key_reuse, idempotency_in_flight, site_limit_reached, site_frozen, scan_in_progress, queue_full, report_not_ready, rate_limited, service_unavailable, internal_error The stable name of the error. New codes can be added, so treat one you do not know like the status alone.
request_id string The id of this request, the same as the Request-Id header. Quote it when you contact support.
errors array of objects One entry for each parameter that needs changing. It has entries with validation_failed, and with a 409 conflict for a site's domain or external_id that another site already uses. With other codes it is normally empty.
errors[].param string The query parameter, header or body member the entry is about.
errors[].code string What is wrong with it, for example invalid or unknown_parameter.
errors[].message string What to change.
feature string With plan_upgrade_required: the feature the plan lacks.
upgrade_url string format uri With plan_upgrade_required and site_limit_reached: where to change the plan.
required_scope string With insufficient_scope: the permission the key lacks.
existing_site_id string format uuid With conflict when a site's domain or external_id is already used by another site of your organisation that your API key can read: the id of that site.
scan_id string format uuid With service_unavailable when a scan could not be queued: the id of the scan, which is listed as failed.
Error codes
Code Status Title
bad_request 400 Bad request
unauthenticated 401 Unauthenticated
forbidden 403 Forbidden
insufficient_scope 403 Insufficient scope
plan_upgrade_required 403 Plan upgrade required
concurrency_limited 429 Too many concurrent requests
not_found 404 Not found
method_not_allowed 405 Method not allowed
conflict 409 Conflict
precondition_failed 412 Precondition failed
payload_too_large 413 Request body too large
credential_in_query 400 Credential in the query string
validation_failed 400, 422 Validation failed
idempotency_key_missing 400 Idempotency key missing
idempotency_key_reuse 422 Idempotency key reused
idempotency_in_flight 409 Request still in progress
site_limit_reached 403 Site limit reached
site_frozen 403 Site frozen
scan_in_progress 409 Scan in progress
queue_full 429 Scan queue full
report_not_ready 409 Report not ready
rate_limited 429 Too many requests
service_unavailable 503 Service unavailable
internal_error 500 Internal error

Listed on