> ## 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 consent banners

> List the account's consent banners, newest first. Requires an
account-scoped API token.




## OpenAPI

````yaml get /consent-banners
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`. Two endpoints take their body unwrapped:
    `POST /auth`, which takes `email` and `password` at the top level, and
    `POST /consent-banners/from-template`, which takes `jurisdiction_id` —
    a selector for which template to build from, not an attribute of the
    banner it creates.

    ## Response envelopes

    Listing endpoints — including `GET /groups` and `GET /accounts` — return
    `{"pagination": {...}, "data": [...]}`. `GET /banner-templates` is the
    exception: it returns `{"data": [...]}` with no pagination, being a fixed
    catalogue rather than a collection of the account's records.
    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:
  /consent-banners:
    get:
      tags:
        - Consent Banners
      summary: List consent banners
      description: |
        List the account's consent banners, newest first. Requires an
        account-scoped API token.
      operationId: listConsentBanners
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/per_page'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: List of consent banners
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/BasePagination'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConsentBanner'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccountTokenRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    account_id:
      name: account_id
      in: query
      description: |
        Which account to act on, as the account's API id. Only meaningful for a
        user API key, which may reach several accounts — an account key already
        identifies exactly one and ignores this.

        Accepted by the endpoints that declare it; others act on the account the
        key resolves to on its own.

        Optional for reads, where it narrows the request to that account.
        Required for writes that declare it when the key can reach more than one
        account: without it the request would act on an account it picked rather
        than one you named, so it is refused with a `400`.
      required: false
      schema:
        type: string
    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:
    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
    ConsentBanner:
      description: |
        Every setting the update endpoint accepts, plus the read-only fields
        below — the response is derived from the same list the API permits, so a
        banner can be read, edited and sent back unchanged.
      allOf:
        - $ref: '#/components/schemas/ConsentBannerWrite'
        - type: object
          properties:
            id:
              type: string
              readOnly: true
            name:
              type: string
            enabled:
              type: boolean
            enable_tcf:
              type: boolean
            force_consent:
              type: boolean
            consent_mode:
              type: string
            consent_duration_days:
              type: integer
            consent_layout:
              type: string
            consent_position:
              type: string
            preferences_control_level:
              type: string
            dark_mode:
              type: string
            language_autodetect:
              type: string
            revision:
              type: integer
              readOnly: true
              description: Bumped when a change requires visitors to consent again
            translations:
              type: array
              readOnly: true
              description: >
                The banner's translations, each with its localized copy
                alongside

                its `id` — so a client can read what it is allowed to write
                rather

                than overwriting fields it cannot see. The `id` is what you send

                back in `banner_languages_attributes` to update or discard one.
              items:
                type: object
                properties:
                  id:
                    type: string
                  language_code:
                    type: string
                    description: ISO 639-1 code
                  consent_title:
                    type:
                      - string
                      - 'null'
                  consent_description:
                    type:
                      - string
                      - 'null'
                  consent_additional_description:
                    type:
                      - string
                      - 'null'
                  banner_accept_btn_text:
                    type:
                      - string
                      - 'null'
                  banner_accept_necessary_btn_text:
                    type:
                      - string
                      - 'null'
                  banner_preferences_btn_text:
                    type:
                      - string
                      - 'null'
                  banner_footer_content:
                    type:
                      - string
                      - 'null'
                  settings_title:
                    type:
                      - string
                      - 'null'
                  settings_description:
                    type:
                      - string
                      - 'null'
                  settings_more_info_title:
                    type:
                      - string
                      - 'null'
                  settings_more_info:
                    type:
                      - string
                      - 'null'
                  privacy_policy_url:
                    type:
                      - string
                      - 'null'
                  do_not_sell_title:
                    type:
                      - string
                      - 'null'
                  do_not_sell_description:
                    type:
                      - string
                      - 'null'
                  preferences_accept_btn_text:
                    type:
                      - string
                      - 'null'
                  preferences_accept_necessary_btn_text:
                    type:
                      - string
                      - 'null'
                  save_preferences_btn_text:
                    type:
                      - string
                      - 'null'
            created_at:
              type: string
              format: date-time
              readOnly: true
            updated_at:
              type: string
              format: date-time
              readOnly: true
      example:
        id: ban1
        name: EU banner
        enabled: true
        enable_tcf: false
        force_consent: false
        consent_mode: opt_in
        consent_duration_days: 180
        consent_layout: box
        consent_position: bottom_center
        consent_title: We use cookies
        consent_description: We use cookies to improve your experience.
        privacy_policy_url: https://example.com/privacy
        preferences_control_level: category_and_services
        dark_mode: light
        language_autodetect: document
        revision: 2
        target_type: selected_countries
        target_countries:
          - DE
          - FR
        target_us_states: []
        target_canadian_regions: []
        translations:
          - id: trn1
            language_code: de
          - id: trn2
            language_code: fr
        created_at: '2023-01-05T10:15:30Z'
        updated_at: '2023-02-01T08:00:00Z'
    ConsentBannerWrite:
      description: >
        Every setting the banner designer exposes, plus whether the banner is

        live. Creating a banner uses ConsentBannerSettings instead, which is
        this

        same set without `enabled`.
      allOf:
        - $ref: '#/components/schemas/ConsentBannerSettings'
        - type: object
          properties:
            enabled:
              type: boolean
              description: Whether the banner is live.
    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
    ConsentBannerSettings:
      type: object
      description: |
        Every setting the banner designer exposes. The response returns the same
        set, so a banner can be read, edited and sent back unchanged. Fields the
        database leaves nullable are declared nullable here too — the response
        returns null for unset copy, and the same shape has to be sendable back.
      properties:
        banner_accept_btn_text:
          type:
            - string
            - 'null'
        banner_accept_necessary_btn_text:
          type:
            - string
            - 'null'
        banner_footer_content:
          type:
            - string
            - 'null'
        banner_preferences_btn_text:
          type:
            - string
            - 'null'
        btn_border_radius:
          type: string
        consent_additional_description:
          type:
            - string
            - 'null'
        consent_button_placement:
          type: string
        consent_description:
          type:
            - string
            - 'null'
        consent_duration_days:
          type: integer
          description: How long a visitor's choice is remembered
        consent_layout:
          type: string
          description: e.g. `box`, `bar`
        consent_mode:
          type: string
          description: e.g. `opt_in`, `opt_out`
        consent_position:
          type: string
          description: e.g. `bottom_center`
        consent_title:
          type:
            - string
            - 'null'
        dark_mode:
          type: string
          description: e.g. `light`, `dark`, `auto`
        do_not_sell_description:
          type:
            - string
            - 'null'
        do_not_sell_title:
          type:
            - string
            - 'null'
        enable_banner_footer:
          type: boolean
        enable_tcf:
          type: boolean
          description: Whether the banner runs in IAB TCF mode
        equal_weight_buttons:
          type: boolean
        floating_preferences_icon_position:
          type: string
        force_consent:
          type: boolean
          description: Whether the page is blocked until the visitor chooses
        language_autodetect:
          type: string
        logo_url_dark:
          type:
            - string
            - 'null'
        logo_url_light:
          type:
            - string
            - 'null'
        modal_border_radius:
          type: string
        name:
          type: string
        preferences_accept_btn_text:
          type:
            - string
            - 'null'
        preferences_accept_necessary_btn_text:
          type:
            - string
            - 'null'
        preferences_control_level:
          type: string
          description: How granular the preferences modal is
        privacy_policy_url:
          type:
            - string
            - 'null'
        save_preferences_btn_text:
          type:
            - string
            - 'null'
        settings_description:
          type:
            - string
            - 'null'
        settings_layout:
          type: string
        settings_more_info:
          type:
            - string
            - 'null'
        settings_more_info_title:
          type:
            - string
            - 'null'
        settings_position_x:
          type: string
        settings_title:
          type:
            - string
            - 'null'
        show_banner_accept_btn:
          type: boolean
        show_banner_accept_necessary_btn:
          type: boolean
        show_banner_close_btn:
          type: boolean
        show_banner_preferences_btn:
          type: boolean
        show_floating_preferences_icon:
          type: boolean
        show_preferences_accept_btn:
          type: boolean
        show_preferences_accept_necessary_btn:
          type: boolean
        show_save_preferences_btn:
          type: boolean
        show_services:
          type: boolean
        swap_buttons:
          type: boolean
        target_canadian_regions:
          type: array
          items:
            type: string
          description: >-
            Province and territory codes, used when `target_type` is
            `selected_canadian_provinces`. Shares a column with
            `target_us_states`.
        target_countries:
          type: array
          items:
            type: string
          description: ISO 3166-1 alpha-2 codes
        target_type:
          type: string
          description: Who sees the banner, e.g. `worldwide`, `selected_countries`
        target_us_states:
          type: array
          items:
            type: string
        button_colors:
          type: object
          additionalProperties:
            type: string
          description: Colour overrides, keyed by button element
  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

````