The Cookies správně API

2. Authentication

You generate the token in the dashboard under Account → API access and send it in the Authorization header as a bearer token. An account always has at most one token.

How to send the token

GET /api/v2/licenses HTTP/1.1
Host: cookies-spravne.cz
Authorization: Bearer cs_2f9Ktz...

Token properties

Managing the token

• Generate token creates a new token and shows it once.
• Regenerate token immediately replaces the existing one. An integration using the old token stops working.
• Revoke token closes access immediately.

Invalid or missing token

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="cookiesspravne", error="invalid_token"
Cache-Control: no-store
Content-Type: application/json

{"error":{"code":"invalid_token","message":"The API token is missing, malformed or no longer valid."}}

3. GET /api/v2/licenses

Returns all licenses your token can reach, sorted by id. No parameters and no pagination. This is where you get the id you then use as license_id when exporting consents.

Request

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://cookies-spravne.cz/api/v2/licenses"

Response

{
  "data": [
    { "id": 1, "domain": "example.cz", "is_active": true,  "created_at": "2025-04-01T09:12:00Z" },
    { "id": 7, "domain": "eshop.cz",   "is_active": false, "created_at": "2026-01-20T14:03:00Z" }
  ]
}

Record fields

4. GET /api/v2/consents

A paginated export of one license's consents. The only required parameter is license_id; the rest have sensible defaults.

Parameters

How parameters are validated

• license_id must be a number. Missing, empty or non-numeric returns 400 invalid_request. Syntactically valid but without access to the license returns 404 license_not_found. The API does not distinguish between “does not exist” and “you have no access”.
• limit that is non-numeric returns 400. A numeric value is clamped to the range 1 to 10000: limit=50000 returns 10000 rows, limit=0 returns one. The value used is always in the response in the meta.limit field.
• order_by and order outside the allowed values, for example order_by=id, return 400 invalid_request.
• from and to accept either a bare date Y-m-d or a full ISO 8601 value, which is used exactly. from=2026-06-01 means 2026-06-01T00:00:00Z, to=2026-06-30 means 2026-06-30T23:59:59Z. Both bounds are inclusive. A non-existent date such as 2026-02-31 returns 400 invalid_date. from later than to returns an empty page.
• The date range applies to the column chosen in order_by. With order_by=updated_at, from therefore means “changed since”, not “created since”.

Response

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://cookies-spravne.cz/api/v2/consents?license_id=1&limit=100"

{
  "data": [
    {
      "id": "9c1f7a2e-5b3d-4e18-9a6c-2f0d81b7e4aa",
      "uid": "aB3xY7kQ",
      "license_id": 1,
      "created_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-04T08:31:00Z",
      "necessary": true,
      "analytics": false,
      "marketing": false,
      "ad_user_data": false,
      "ad_personalization": false,
      "was_shown": true,
      "was_dismissed": false
    }
  ],
  "meta": {
    "count": 100,
    "limit": 100,
    "order": "asc",
    "order_by": "created_at",
    "has_more": true,
    "next_cursor": "v1.eyJ0IjoiMjAyNi0wNi0wMSAxMDowMDowMCJ9"
  },
  "links": {
    "next": "https://cookies-spravne.cz/api/v2/consents?license_id=1&limit=100&cursor=v1.eyJ0IjoiMjAyNi0wNi0wMSAxMDowMDowMCJ9"
  }
}

Record fields

The internal reference to the configuration version the visitor saw and the flag for imports from the older system are not exported. If you need them, write to us at podpora@cookies-spravne.cz.

The meta and links fields

links.next is built from the query string of the incoming request, with cursor added. It therefore also keeps the limit, order_by, from and to the pagination started with.

The consent data model

The bar cares about the visitor's current decision, not their history. A write is therefore an upsert on the license_id and uid pair: one row per visitor, overwritten on every change of choice.

The was_shown and was_dismissed flags are in the export because without them three different situations look the same, with all categories false:

5. Sorting and pagination

For regular data imports, always sort by updated_at. Pagination uses a cursor that remembers the filters of the original query and does not expire.

Sorting and data freshness

The reason is the data model: a consent is a state, not an event. When a visitor changes their mind, their row is overwritten but created_at stays old. When sorting by created_at, such a record stays in its old position and your incremental import misses it.

Pagination

One page returns at most 10,000 records. Further pages are read with the cursor parameter, whose value you will find in the response in meta.next_cursor. links.next gives you the full address of the next page straight away, with all the original parameters.

GET /api/v2/consents?license_id=1&limit=2

{ "data": [ … 2 rows … ],
  "meta": { "count": 2, "limit": 2, "has_more": true, "next_cursor": "v1.eyJ0IjoiMjAyNi0w…" },
  "links": { "next": "…&cursor=v1.eyJ0IjoiMjAyNi0w…" } }

GET /api/v2/consents?license_id=1&limit=2&cursor=v1.eyJ0IjoiMjAyNi0w…

{ "data": [ … 2 rows … ],
  "meta": { "count": 2, "limit": 2, "has_more": true, "next_cursor": "v1.eyJ0IjoiMjAyNi0x…" },
  "links": { "next": "…&cursor=v1.eyJ0IjoiMjAyNi0x…" } }

GET /api/v2/consents?license_id=1&limit=2&cursor=v1.eyJ0IjoiMjAyNi0x…

{ "data": [ … 1 row … ],
  "meta": { "count": 1, "limit": 2, "has_more": false, "next_cursor": null },
  "links": { "next": null } }

Another page exists as long as has_more === true and links.next !== null. The has_more value is derived from loading one row more than is returned.

Cursor properties

• It keeps the filters of the original query. Using it with a different license_id, order, order_by, from or to returns 400 cursor_mismatch.
• An invalid cursor returns 400 invalid_cursor.
• It does not expire. It points to a position in the ordering, not to a query result.

6. Limits and errors

With a valid token you have 120 requests per minute. Every error response has the same shape: an error object with code and message fields.

Limits

With a valid token, the limit is keyed to the account, not the IP. Servers behind one NAT address therefore do not share a budget, but two machines of the same account do. With limit=10000 the ceiling corresponds to 1,200,000 rows per minute.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"error":{"code":"rate_limited","message":"Too many requests."}}

The 429 response carries no Retry-After header and no X-RateLimit-* headers. The window is a fixed minute, so it is enough to wait and repeat the request.

Error response shape

All errors, including 500, have the same shape:

{
  "error": {
    "code": "invalid_token",
    "message": "The API token is missing, malformed or no longer valid."
  }
}

Error codes

Example

GET /api/v2/consents?license_id=abc

HTTP/1.1 400 Bad Request

{"error":{"code":"invalid_request","message":"A numeric license_id is required."}}

7. Example calls

Three ready-to-use samples: a full export to JSONL, incremental reading of changes and loading a single page.

Full export to JSONL

Bash with curl and jq. It goes through all pages via links.next as long as another one exists.

#!/usr/bin/env bash
set -euo pipefail

TOKEN="cs_…"
URL="https://cookies-spravne.cz/api/v2/consents?license_id=1&limit=1000"

while [ -n "$URL" ]; do
  BODY=$(curl -sS -H "Authorization: Bearer $TOKEN" "$URL")
  echo "$BODY" | jq -c '.data[]' >> consents.jsonl
  URL=$(echo "$BODY" | jq -r '.links.next // ""')
done

Incremental reading of changes

JavaScript. It reads records changed since a given moment, sorts by updated_at and can wait when the limit is exceeded.

const TOKEN = process.env.COOKIES_SPRAVNE_TOKEN;
const BASE = 'https://cookies-spravne.cz/api/v2/consents';

async function* changes(licenseId, since) {
  let url = `${BASE}?license_id=${licenseId}&order_by=updated_at&order=asc&limit=1000`
    + (since ? `&from=${encodeURIComponent(since)}` : '');

  while (url) {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } });

    if (res.status === 429) {
      await new Promise(resolve => setTimeout(resolve, 60_000));
      continue;
    }

    if (!res.ok) {
      const { error } = await res.json();
      throw new Error(`${res.status} ${error.code}: ${error.message}`);
    }

    const { data, links } = await res.json();

    yield* data;

    url = links.next;
  }
}

A single page in PHP

<?php

$token = getenv('COOKIES_SPRAVNE_TOKEN');

$context = stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => "Authorization: Bearer {$token}\r\n",
    ],
]);

$url = 'https://cookies-spravne.cz/api/v2/consents?' . http_build_query([
    'license_id' => 1,
    'order_by' => 'updated_at',
    'order' => 'asc',
    'limit' => 1000,
]);

$page = json_decode(file_get_contents($url, false, $context), true);

8. Legacy API (v1)

The original system's endpoints remain available at the same addresses and return data in the same format, so existing integrations keep working without changes.

Legacy API authentication

The legacy API is not authenticated with the API token but with the legacy API key you received when access was activated in the original system. If we hold it for your account, you will find it in the dashboard under Account → API access. If you do not see it there, write to us at podpora@cookies-spravne.cz.

The key is sent in the Authorization header. For backward compatibility the Authentication header, which the original documentation gave, is also accepted:

Authorization: Bearer xxxxxxxxx
Authentication: Bearer xxxxxxxxx

Responses are always application/json. Errors have the same shape and codes as v2, and the same limits apply.

GET /api/consent-report

Returns users' consents. Supports pagination and filtering.

Combining from and to creates an interval that includes from and excludes to. For example ?from=2022-01-01&to=2022-02-01 returns the whole of January 2022. Filtering is by the date consent was first given, date_of_consent, and records are sorted by it in ascending order.

Response headers

Example

curl -sS -H "Authorization: Bearer $LEGACY_KEY" \
  "https://cookies-spravne.cz/api/consent-report?key=bstl7sn95ns7sno97s1q&from=2022-01-01&to=2022-02-01&page=1"

[
  {
    "_id": { "$oid": "9c1f7a2e-5b3d-4e18-9a6c-2f0d81b7e4aa" },
    "uid": "CxQ25iVbozc2o82J4RcuX1Lv5DoXpO",
    "key": "bstl7sn95ns7sno97s1q",
    "necessary": "1",
    "analytics": "0",
    "marketing": "1",
    "config": { "$oid": "4812" },
    "date_of_consent": "1644842294"
  }
]

GET /api/consent-configs

Returns all versions of the bar's settings and texts that were shown to visitors. Consents may be tied to a different wording of the bar, so each consent has a reference to a specific version in the config field. The only parameter is the required key, with the same meaning as above.

[
  {
    "_id": { "$oid": "4812" },
    "modified": 1644236417,
    "texts": {
      "cs": {
        "reject_all": "Odmítnout",
        "cookie_policy": "Více o cookies",
        "iframe_no_cookies": "Pro zobrazení tohoto obsahu povolte prosím ukládání cookies."
      }
    }
  }
]

_id.$oid matches the config.$oid value in the consent listing, modified is a Unix timestamp of when this version was first shown, and texts contains the bar's texts by language.

Differences from the original system

• A consent is one record per visitor. When a visitor changes their choice, the record is overwritten and date_of_consent remains the date of the first consent. To track changes, use API v2 with order_by=updated_at.
• Errors return JSON with an error object. For example, a missing key returns 400 invalid_request.