Categories

Cookie categories organize tracking technologies by purpose. Every site starts with three default categories (essential, statistics, marketing) that cannot be deleted. You can create additional categories via the API.

In React apps, use the ConsentGate component with a category prop matching these slugs to conditionally render content based on consent.

GET

List categories

GET /sites/{id}/categories

Returns all cookie categories for a site, including both default and custom categories.

Path parameters

idstringrequired

Site ID (UUID)

Response fields

Field	Type	Description
`id`	string	Category ID (UUID)
`siteId`	string	Parent site ID
`slug`	string	URL-safe identifier, auto-generated from name
`name`	string	Display name shown in the consent banner
`description`	string	Explains what this category is used for
`isRequired`	boolean	If `true`, category cannot be opted out of (e.g. essential)
`isDefault`	boolean	If `true`, this is a system default category and cannot be deleted
`sortOrder`	integer	Display order in the consent banner

curl https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/categories \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7"

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/categories`,
  { headers: { Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7' } },
);
const categories = await res.json();

import requests

res = requests.get(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/categories",
    headers={"Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7"},
)
categories = res.json()

Response 200

[
  {
    "id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
    "siteId": "e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789",
    "slug": "essential",
    "name": "Essential",
    "description": "Cookies required for the site to function",
    "isRequired": true,
    "isDefault": true,
    "sortOrder": 0,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  },
  {
    "id": "d2e3f4a5-b6c7-8901-def0-234567890123",
    "siteId": "e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789",
    "slug": "statistics",
    "name": "Statistics",
    "description": "Analytics and performance tracking",
    "isRequired": false,
    "isDefault": true,
    "sortOrder": 1,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
]

POST

Create a category

POST /sites/{id}/categories

Creates a new cookie category. The slug is auto-generated from the name.

Path parameters

idstringrequired

Site ID (UUID)

Request body

namestringrequired

Display name for the category (e.g. 'Personalization')

descriptionstring

Explains what this category is used for, shown in consent preferences

Error responses

Status	Description
`422`	Missing required field or invalid name

curl -X POST https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/categories \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Personalization",
    "description": "Cookies used to remember your preferences and customize your experience"
  }'

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/categories`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Personalization',
      description: 'Cookies used to remember your preferences',
    }),
  },
);
const category = await res.json();

import requests

res = requests.post(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/categories",
    headers={
        "Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7",
        "Content-Type": "application/json",
    },
    json={
        "name": "Personalization",
        "description": "Cookies used to remember your preferences",
    },
)
category = res.json()

Response 201

{
  "id": "f4a5b6c7-d8e9-0123-4567-890abcdef012",
  "siteId": "e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789",
  "slug": "personalization",
  "name": "Personalization",
  "description": "Cookies used to remember your preferences and customize your experience",
  "isRequired": false,
  "isDefault": false,
  "sortOrder": 3,
  "createdAt": "2025-03-20T14:22:00.000Z",
  "updatedAt": "2025-03-20T14:22:00.000Z"
}

PATCH

Update a category

PATCH /sites/{id}/categories/{catId}

Partially updates a cookie category. Only include the fields you want to change.

Path parameters

idstringrequired

Site ID (UUID)

catIdstringrequired

Category ID (UUID)

Request body

namestring

Updated display name

descriptionstring

Updated description

sortOrderinteger

Updated display order

curl -X PATCH https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/categories/f4a5b6c7-d8e9-0123-4567-890abcdef012 \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7" \
  -H "Content-Type: application/json" \
  -d '{"name": "Preferences", "sortOrder": 2}'

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/categories/${catId}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'Preferences', sortOrder: 2 }),
  },
);
const category = await res.json();

import requests

res = requests.patch(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/categories/{cat_id}",
    headers={
        "Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7",
        "Content-Type": "application/json",
    },
    json={"name": "Preferences", "sortOrder": 2},
)
category = res.json()

Response 200

Returns the full updated category object.

DELETE

Delete a category

DELETE /sites/{id}/categories/{catId}

Deletes a cookie category. Default categories (essential, statistics, marketing) cannot be deleted.

Path parameters

idstringrequired

Site ID (UUID)

catIdstringrequired

Category ID (UUID)

Error responses

Status	Description
`400`	Cannot delete a default category
`404`	Category not found

curl -X DELETE https://api.consentlayer.com/api/v1/sites/e1a2b3c4-d5e6-7f89-0a1b-2c3d4e5f6789/categories/f4a5b6c7-d8e9-0123-4567-890abcdef012 \
  -H "Authorization: Bearer cl_key_live_a8f2b9c4d1e6f3a7"

const res = await fetch(
  `https://api.consentlayer.com/api/v1/sites/${siteId}/categories/${catId}`,
  {
    method: 'DELETE',
    headers: { Authorization: 'Bearer cl_key_live_a8f2b9c4d1e6f3a7' },
  },
);
const result = await res.json();

import requests

res = requests.delete(
    f"https://api.consentlayer.com/api/v1/sites/{site_id}/categories/{cat_id}",
    headers={"Authorization": "Bearer cl_key_live_a8f2b9c4d1e6f3a7"},
)
result = res.json()

Response 200

{
  "success": true
}