> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cookiechimp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List categories

> List all categories for the current account. Requires an account-scoped API token.



## OpenAPI

````yaml get /categories
openapi: 3.1.0
info:
  title: CookieChimp API
  description: |
    API for CookieChimp.com.

    ## Request bodies

    Resource endpoints expect the resource wrapped under its own key, e.g.
    `{"category": {"name": "Analytics"}}` rather than a bare object.
    `PUT /password` wraps in `user`. `POST /auth` is the exception: it takes
    `email` and `password` at the top level.

    ## Response envelopes

    Listing endpoints — including `GET /groups` and `GET /accounts` — return
    `{"pagination": {...}, "data": [...]}`. Most single-resource endpoints
    return `{"data": {...}}`; a single group or account is returned unwrapped.
    Resource-deletion endpoints return `{"message": "..."}`; `DELETE /auth`
    returns an empty object.
  version: 1.2.0
servers:
  - url: https://cookiechimp.com/api/v1
security:
  - authorization: []
paths:
  /categories:
    get:
      tags:
        - Categories
      summary: List categories
      description: >-
        List all categories for the current account. Requires an account-scoped
        API token.
      operationId: listCategories
      parameters:
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: List of categories
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/CategoryPagination'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Category'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccountTokenRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    per_page:
      name: per_page
      in: query
      description: |
        Number of records to return per page. The effective range is 1–50; any
        value outside it is accepted but falls back to the default of 20.
      required: false
      schema:
        type: integer
        default: 20
    page:
      name: page
      in: query
      description: |
        Page number. Must be a positive integer; anything else returns a `400`.
        Requesting a page past the end returns the last page.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
  schemas:
    CategoryPagination:
      allOf:
        - $ref: '#/components/schemas/BasePagination'
      example:
        prev_url: /api/v1/categories?page=
        next_url: /api/v1/categories?page=2
        count: 68
        page: 1
        prev: null
        next: 2
    Category:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: Unique identifier for the category
        name:
          type: string
          description: Name of the category that is displayed to users
        description:
          type: string
          description: Description of the category that is displayed to users
        slug:
          type: string
          description: URL-friendly identifier for the category
        required:
          type: boolean
          description: Whether the category is required for the website to function
        default_language:
          type: string
          description: Language code the name and description are written in
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      example:
        id: essential
        name: Essential
        description: Cookies essential for website functionality
        slug: essential
        required: true
        default_language: en
        created_at: '2023-01-01T00:00:00Z'
        updated_at: '2023-01-02T00:00:00Z'
    BasePagination:
      type: object
      properties:
        prev_url:
          type: string
          description: Path to get the previous page
        next_url:
          type: string
          description: Path to get the next page
        count:
          type: integer
          description: Total number of records across all pages
        page:
          type: integer
          description: Current page
        prev:
          type:
            - integer
            - 'null'
          description: Previous page number, or null on the first page
        next:
          type:
            - integer
            - 'null'
          description: Next page number, or null on the last page
    Error:
      type: object
      description: |
        The standard error envelope, used for authentication, authorization,
        pagination and not-found errors.
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
      example:
        errors:
          - code: 401
            message: Invalid API Key
  responses:
    BadRequest:
      description: Invalid pagination parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: 400
                message: Invalid page parameter
    AccountTokenRequired:
      description: |
        Missing or invalid API token, or a token that does not resolve to an
        account. Account-scoped endpoints accept an account token, or a user
        token whose user belongs to an account; partner tokens are rejected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: 401
                message: API key must belong to an account
    RateLimited:
      description: |
        Too many requests. The general limit is 300 requests per 5 minutes per
        API token; the auth endpoints are throttled more tightly per IP.
      headers:
        Retry-After:
          description: Seconds until the current rate-limit window resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: 429
                message: Too many requests. Please retry later.
  securitySchemes:
    authorization:
      type: http
      scheme: bearer
      description: API token obtained from the login endpoint or the dashboard

````