Skip to main content
Welcome to the CookieChimp API. We provide a RESTful API that allows you to access all the data on CookieChimp. You can use our API to integrate your applications, services, and workflows with our platform.

​
Base URL

All API requests should be made to:

​
Authentication

To authenticate with the CookieChimp API, you need an API token. Include it in the Authorization header of your HTTP requests as a Bearer token:

​
Obtaining Your API Token

There are two ways to get an API token:
  1. Via the Dashboard: Go to your API Tokens settings page to create and manage tokens.
  2. Via the API: Use the Login endpoint with your email and password to receive a token.

​
Token Types

API tokens can belong to different bearer types:
  • User tokens — Access resources on behalf of a user across their accounts.
  • Partner tokens — Access partner-level resources like groups.
  • Account tokens — Access resources scoped to a specific account.
Most endpoints are scoped to a single account. These accept an account token, or a user token whose user belongs to an account. A partner token does not resolve to one account, so those endpoints reject it with:
The group endpoints work the other way around: they require a partner token and reject user and account tokens with API key must belong to a partner. The account endpoints accept all three.

​
Rate Limits

To ensure fair usage of the API, we limit the number of requests you can make. The general limit is 300 requests per 5 minutes, counted per API token (or per IP address when no token is sent). A few endpoints have tighter limits, counted per IP address: If you exceed a limit you receive a 429 Too Many Requests response with a Retry-After header giving the number of seconds until the window resets.

​
Pagination

List endpoints support pagination with the following query parameters: Paginated responses include a pagination object with prev_url, next_url, count, page, prev, and next fields. count is the total number of records across all pages, not the number of pages. prev and next are null on the first and last page. page must be a positive integer — anything else returns a 400. A per_page outside 1–50 falls back to 20, and requesting a page past the end returns the last page.

​
Request Bodies

Resource endpoints expect the resource wrapped under its own key rather than at the top level:
The wrapper matches the resource: category, storage_item, group, account_user, account_invitation, and user for Change password. Log in is the exception — it takes email and password at the top level, unwrapped.

​
Response Envelopes

Group and account listings use the standard list envelope in the first row — only their single-resource responses are unwrapped.

​
Errors

The API returns standard HTTP status codes. Authentication, pagination and not-found errors return an errors array of objects with code and message:
Validation errors on categories, storage items and account invitations return an errors array of objects with a single human-readable error:
Three endpoints — Create group, Update group and Update account user — render the model’s errors directly instead, as an object keyed by attribute:
Every other validation failure uses the errors array above, including refusing to remove an account owner. Two specific failures return a single top-level error string: rejected credentials on Log in, and a wrong current password or invalid new password on Change password.
This applies only to those two failures. Everything else on those endpoints — a missing or invalid bearer token, or a rate limit — uses the errors array shape above.