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

# Create Collection

> Create a collection. Clauses are optional so an empty collection can be curated later.

Invalid brand, website, or category ids, including ids in exclude lists, return 422.



## OpenAPI

````yaml post /v1/collections
openapi: 3.1.0
info:
  title: Channel3 API
  version: 0.1.0
servers:
  - url: https://api.trychannel3.com
    description: Production
security: []
paths:
  /v1/collections:
    post:
      tags:
        - collections
      summary: Create Collection
      description: >-
        Create a collection. Clauses are optional so an empty collection can be
        curated later.


        Invalid brand, website, or category ids, including ids in exclude lists,
        return 422.
      operationId: create_collection_v1_collections_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API Key
                  value:
                    detail: >-
                      Unauthorized. Missing authentication key. Make sure to
                      attach an x-api-key with your request. Need help? Reach
                      out to support@channel3.ai.
                invalid_key:
                  summary: Invalid API Key
                  value:
                    detail: >-
                      API key was provided but is invalid. Need help? Reach out
                      to support@channel3.ai.
              schema:
                $ref: '#/components/schemas/app__routers__utils__ErrorResponse'
        '402':
          description: Payment required
          content:
            application/json:
              examples:
                credits_exhausted:
                  summary: API key out of credits
                  value:
                    detail: >-
                      You have used all of your free credits. Add a payment
                      method to continue.
                mpp_challenge:
                  summary: MPP Tempo payment required
                  value:
                    detail: >-
                      Payment required. Satisfy the MPP Tempo challenge in
                      WWW-Authenticate.
              schema:
                $ref: '#/components/schemas/app__routers__utils__ErrorResponse'
        '422':
          description: Validation error or invalid ids, including exclude lists
          content:
            application/json:
              example:
                detail: >-
                  Collection was not created. Invalid brand_ids:
                  'brand_nike_abc123'
              schema:
                $ref: '#/components/schemas/app__routers__utils__ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__routers__utils__ErrorResponse'
              example:
                detail: Internal Server Error
      security:
        - APIKeyHeader: []
      x-codeSamples:
        - lang: python
          label: Python
          source: |
            from channel3_sdk import Channel3
            from channel3_sdk.environment import Channel3Environment

            client = Channel3(
                api_key="<value>",
                environment=Channel3Environment.PRODUCTION,
            )

            client.collections.create()
        - lang: typescript
          label: TypeScript
          source: |
            import { Channel3 } from "@channel3/sdk";

            const client = new Channel3({ apiKey: "YOUR_API_KEY" });

            await client.collections.create();
components:
  schemas:
    CreateCollectionRequest:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Display name. Defaults to 'Collection {n}' for this account or user.
        description:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Description
          description: Optional vendor-facing notes for this collection.
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: >-
            Optional partner user id. Scopes the collection to one end user and
            serves as the default x-user-id on collection-scoped search, browse,
            and conversation requests when the caller omits that header.
        clauses:
          items:
            $ref: '#/components/schemas/CollectionClauseInput'
          type: array
          title: Clauses
          description: >-
            OR across clauses. Within a clause, brand_ids, website_ids, and
            category_ids are ORed inside each list and ANDed across lists.
            Exclusions narrow that clause only and do not apply across the OR.
            Empty is allowed so a collection can be created before any items are
            added.
      additionalProperties: false
      type: object
      title: CreateCollectionRequest
    CollectionResponse:
      properties:
        collection_id:
          type: string
          title: Collection Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        clauses:
          items:
            $ref: '#/components/schemas/CollectionClause'
          type: array
          title: Clauses
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - collection_id
        - name
        - clauses
        - created_at
        - updated_at
      title: CollectionResponse
    app__routers__utils__ErrorResponse:
      properties:
        detail:
          anyOf:
            - type: string
            - items:
                additionalProperties: true
                type: object
              type: array
          title: Detail
      type: object
      required:
        - detail
      title: ErrorResponse
    CollectionClauseInput:
      properties:
        brand_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Brand Ids
          description: >-
            OR within this list (any slot). AND with the clause's other lists.
            OR against other clauses.
        website_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Website Ids
          description: >-
            Merchant ids; OR within this list (any matching offer). AND with the
            clause's other lists. Domains are accepted on write and stored as
            merchant ids. Also scopes displayed offers for products matched only
            by website-scoped clauses.
        category_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Category Ids
          description: OR within this list. AND with the clause's other lists.
        product_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Product Ids
        exclude_brand_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Brand Ids
          description: Clause-only; products missing a brand id still match.
        exclude_website_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Website Ids
          description: Clause-only; domains become ids; another offer keeps the product.
        exclude_category_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Category Ids
          description: Clause-only; products missing category_ids still match.
      additionalProperties: false
      type: object
      title: CollectionClauseInput
      description: Clause payload for create / add_clauses (server mints clause_id).
    CollectionClause:
      properties:
        brand_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Brand Ids
          description: >-
            OR within this list (any slot). AND with the clause's other lists.
            OR against other clauses.
        website_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Website Ids
          description: >-
            Merchant ids; OR within this list (any matching offer). AND with the
            clause's other lists. Domains are accepted on write and stored as
            merchant ids. Also scopes displayed offers for products matched only
            by website-scoped clauses.
        category_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Category Ids
          description: OR within this list. AND with the clause's other lists.
        product_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Product Ids
        exclude_brand_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Brand Ids
          description: Clause-only; products missing a brand id still match.
        exclude_website_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Website Ids
          description: Clause-only; domains become ids; another offer keeps the product.
        exclude_category_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Category Ids
          description: Clause-only; products missing category_ids still match.
        clause_id:
          type: string
          title: Clause Id
      additionalProperties: false
      type: object
      required:
        - clause_id
      title: CollectionClause
      description: Persisted clause with a stable server-minted id.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.