> ## 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.

# Create group

> Create a new group under your partner. Requires a partner API token.



## OpenAPI

````yaml post /groups
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:
  /groups:
    post:
      tags:
        - Groups
      summary: Create group
      description: Create a new group under your partner. Requires a partner API token.
      operationId: createGroup
      requestBody:
        description: Group to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreateRequest'
      responses:
        '201':
          description: Created group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/PartnerTokenRequired'
        '422':
          $ref: '#/components/responses/ModelValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    GroupCreateRequest:
      type: object
      properties:
        group:
          $ref: '#/components/schemas/GroupCreate'
      required:
        - group
      example:
        group:
          name: Example Ltd
          external_id: ABC_123
          max_pageviews_per_month: 500000
          max_unique_visitors_per_month: 100000
    Group:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: Unique identifier for the group
        partner:
          type: string
          readOnly: true
          description: Name of the partner the group belongs to
        name:
          type: string
          description: Name of the group
        external_id:
          type: string
          description: External ID set by the partner
        max_pageviews_per_month:
          type:
            - integer
            - 'null'
          description: Maximum number of pageviews per month
        max_unique_visitors_per_month:
          type:
            - integer
            - 'null'
          description: Maximum number of unique visitors per month
      example:
        id: abc123
        partner: partner_one
        name: Example Ltd
        external_id: ABC_123
        max_pageviews_per_month: 500000
        max_unique_visitors_per_month: 100000
    GroupCreate:
      type: object
      properties:
        name:
          type: string
          description: Name of the group
        external_id:
          type: string
          description: External ID set by the partner
        max_pageviews_per_month:
          type: integer
          description: Maximum number of pageviews per month
        max_unique_visitors_per_month:
          type: integer
          description: Maximum number of unique visitors per month
      required:
        - name
        - external_id
    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
    ModelValidationError:
      type: object
      description: |
        Returned by group create/update and account-user update, which render
        the model's errors directly: an object keyed by attribute name. Other
        validation failures — including removing an account owner — use
        `ValidationError`.
      additionalProperties:
        type: array
        items:
          type: string
      example:
        name:
          - can't be blank
        external_id:
          - has already been taken
  responses:
    PartnerTokenRequired:
      description: >-
        Missing or invalid API token, or a token that does not belong to a
        partner
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - code: 401
                message: API key must belong to a partner
    ModelValidationError:
      description: The record could not be saved
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ModelValidationError'
    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

````