Skip to content
Start free Sign in

Make your first API request

Agency plan

Last updated

Available on the Agency plan

This feature is included in the Agency plan and the plans above it. See pricing

The Kukie.io API lets your own software manage the sites of your organisation: create them, change their banners, start cookie scans and read consent records. This guide takes you from an API key to your first answers. Every operation is in the API reference.

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

Before you start

  • Your organisation is on a plan that includes the API.
  • You are an owner or admin of the organisation. Editors cannot create API keys.
  • Your organisation is not on a free trial.

Create an API key

  1. In your Kukie.io account, open the account menu and select API keys.
  2. Select Create key.
  3. Enter a Name that tells you later what the key is for.
  4. Under Sites, select All sites, including sites added later. Only a key that reaches all sites can create a site.
  5. Under What the key can do, select Site provisioning. The guide to keys and permissions lists what each choice allows.
  6. Choose when the key expires under Expires after.
  7. Read the API Terms and select the checkbox I accept the API Terms.
  8. Enter your Password if the dialog asks for it, and your Authentication code if your account uses two-factor authentication. Then select Create key.
  9. Copy the key and store it in a secret manager. Kukie.io shows it only once.

The examples below read the key from an environment variable named KUKIE_API_KEY. Set it without typing the key into a command, because the shell keeps the commands you type in its history. In bash or zsh, this command waits for you to paste the key and press Enter, and shows nothing while you do:

read -rs KUKIE_API_KEY && export KUKIE_API_KEY

The variable lasts until you close that terminal window.

Send your first request

The base URL is https://api.kukie.io. Send the key in the Authorization header of every request, never in the URL.

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

The answer describes the key that sent the request, its organisation and plan, and the rate limits. It needs no permission, so it is a quick way to check that a key works.

Create a site

Creating a site needs the sites:write permission and an Idempotency-Key header. The header is a value of your own that names the request, so that sending it again after a timeout does not create a second site.

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"}'

The answer is the new site. Its id is the identifier you use in the URL of every other site operation, and embed.html is the script tag that installs the banner on the site's pages.

Emails about sites and deletions

  • For a site created through the API, Kukie.io does not send the site verification reminder or the scan completed email. To receive them, an owner or admin turns on Emails about sites created through the API on the API keys page.
  • When sites are deleted through the API, the owner and every admin of the organisation get an email that names the API key. No setting stops this email.

Check it worked

List your sites. The new site is the first one, because the list is newest first:

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

The site also appears in your Kukie.io dashboard, like a site you add there.

Escape text that comes from websites

Answers about cookies, cookie categories, scans, installation checks and consent records can hold text that a scanned website, a visitor's browser or a person wrote, such as cookie names, page addresses and descriptions. Such an answer names those members in untrusted_fields. Kukie.io removes control characters from such a value but not markup, so escape it wherever your software shows it.

Use Postman or Bruno

The API serves its OpenAPI document at https://api.kukie.io/v1/openapi.json. Both apps can build a collection from it.

  • Postman: select Import, enter the document's URL, and choose to generate a collection. Then set the collection's authorisation to Bearer Token with your API key.
  • Bruno: select Import Collection, choose OpenAPI and the URL option, and enter the same address. Then set Bearer authentication on the collection.
Was this helpful?

Listed on