---
title: "Create a new collection"
method: POST
path: "/public/v1/collections"
tags: ["Collections - Management"]
---

# Create a new collection

`POST /public/v1/collections`

Create a new collection with the specified properties.

The collection will be created with "Customer" scope by default unless explicitly specified otherwise. All required fields must be provided and will be validated.

**Note**: The collection will be automatically subscribed to your account upon creation, and you will become the collection owner.

**Request:**
The request body includes collection name (required) and optional fields for scope, lanes, tiersEnabled, and parentId. See the `PublicCollectionPayload` schema for complete field definitions and validation rules.

**Validation Rules:**
- Collection names must be unique within the specified scope
- The `tiersEnabled` field cannot be changed after collection creation
- The `parentId` field is accepted but currently not used - collection hierarchy is managed internally

**What happens when you create a collection:**

1. **Collection Creation**: A new active collection is created with the specified properties
2. **User Subscription**: You are automatically subscribed to the collection and become its owner
3. **User Activity**: For Customer scope collections, the creation is logged in your user activity
4. **Audit Trail**: The creation is recorded in the audit log with:
   - The user who created the collection
   - Timestamp of the operation
   - Collection details (name, scope, type)
   - Reference to the public API endpoint used
   - Audit comment: "Collection created via Public API"

**Important Notes:**

- Collection names must be unique within the specified scope - attempting to use a duplicate name will result in `409 Conflict`
- Once created, the `scope` and `tiersEnabled` fields cannot be changed
- The collection will be empty (no targets) initially - use the Collection Targets API (`POST /public/v1/collections/{collectionId}/targets`) to add suppliers to the collection
- You automatically become the owner of the collection upon creation
- All collection operations are audited for compliance and tracking purposes

**Required Permission**: `CREATE_COLLECTION`

## Request body

- PublicCollectionPayload
  - `scope` 'User' | 'Customer' | 'Featured', required
  - `name` string, required
  - `lanes` boolean, required
  - `tiersEnabled` boolean, required
  - `parentId` integer, nullable

## Response `201`

201 Created - Collection created successfully. The creation has been audited with the comment 'Collection created via Public API'.

- PublicCollectionDTO
  - `id` integer, required
  - `uuid` string, uuid, required
  - `scope` 'User' | 'Customer' | 'Featured', required
  - `type` 'Default' | 'Commodity' | 'Ariba', required
  - `name` string, required
  - `count` integer, nullable
  - `lanes` boolean, required
  - `tiersEnabled` boolean, required
  - `parentId` integer, nullable
  - `children` PublicCollectionDTO[], required
  - `updatedAt` string, date-time, nullable

## Other responses

- `400` — 400 Bad Request - Invalid request payload or validation errors. The request body is malformed or contains invalid data.
- `403` — 403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.
- `409` — 409 Conflict - A collection with the same name already exists in the specified scope. Collection names must be unique within each scope.
- `429` — 429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.
- `500` — 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.

---

[API](https://skmtc.net/prewave/apis/public-prewave-api.md) · [All operations](https://skmtc.net/prewave/apis/public-prewave-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prewave/public-prewave-api/revisions/466169815b78/schema)