> For the complete documentation index, see [llms.txt](https://pixyleai.gitbook.io/pixyle.ai-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pixyleai.gitbook.io/pixyle.ai-documentation/api-endpoints/collection-processing-api/routes/collections.md).
# Collections
## Get all collections
> Retrieve all collections for the current user with pagination support.\
> Returns a paginated list of collections with metadata and collection details.
```json
{"openapi":"3.0.3","info":{"title":"Dataset Upload API","version":"1.0.0"},"servers":[{"url":"https://api.pixyle.ai/main/v1"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication"}},"schemas":{"CollectionsListResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/PaginationMeta"},"result":{"type":"array","items":{"$ref":"#/components/schemas/CollectionListItem"}}},"required":["meta","result"]},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number"},"size":{"type":"integer","description":"Number of items per page"},"total_pages":{"type":"integer","description":"Total number of pages"},"total":{"type":"integer","description":"Total number of items"}},"required":["page","size","total_pages","total"]},"CollectionListItem":{"allOf":[{"$ref":"#/components/schemas/CollectionBase"},{"type":"object","properties":{"images":{"type":"array","description":"List of signed image URLs for the collection","items":{"type":"string","format":"uri"}}},"required":["images"]}]},"CollectionBase":{"type":"object","properties":{"id":{"type":"integer","description":"Collection ID"},"name":{"type":"string","description":"Collection name"},"product_count":{"type":"integer","description":"Number of products in the collection"},"processed_products_percentage":{"type":"number","format":"float","description":"Percentage of processed products"},"verified_products_percentage":{"type":"number","format":"float","description":"Percentage of verified products"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","name","product_count","processed_products_percentage","verified_products_percentage","created_at","updated_at"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"Error code"}},"required":["error","code"]}},"responses":{"Unauthorized":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/collections":{"get":{"summary":"Get all collections","description":"Retrieve all collections for the current user with pagination support.\nReturns a paginated list of collections with metadata and collection details.\n","tags":["Collections"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"minimum":1},"description":"Number of current page."},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":7,"minimum":1,"maximum":20},"description":"Number of collections per page. The maximum value can be 20."}],"responses":{"200":{"description":"Collections retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionsListResponse"}}}},"400":{"description":"Bad request - validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Upload a collection
> This endpoint allows you to upload a collection file to the Pixyle API. The collection will be processed\
> and stored in the system. The endpoint supports CSV and JSON file formats.\
> \
> \*\*Rate Limits:\*\*\
> \- 1 request/second per client\
> \- Simultaneous processing limit: 10 collections per client (can be adjusted upon request)
```json
{"openapi":"3.0.3","info":{"title":"Dataset Upload API","version":"1.0.0"},"servers":[{"url":"https://api.pixyle.ai/main/v1"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication"}},"schemas":{"CollectionUploadRequest":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The dataset file to upload (CSV or JSON)"}},"required":["file"]},"CollectionUploadResponse":{"type":"object","properties":{"message":{"type":"string","description":"Success message indicating the status of the upload"},"id":{"type":"integer","description":"The unique identifier of the created collection"},"name":{"type":"string","description":"The final name of the collection (may be modified to resolve duplicates)"},"product_count":{"type":"integer","description":"Number of products/listings in the collection"},"image_count":{"type":"integer","description":"Number of images in the collection"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the collection was created"}},"required":["message","id","name","product_count","image_count","created_at"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"Error code"}},"required":["error","code"]}},"responses":{"Unauthorized":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientPermissionsAndLimit":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimitExceeded":{"description":"Too Many Requests - rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/collections":{"post":{"summary":"Upload a collection","description":"This endpoint allows you to upload a collection file to the Pixyle API. The collection will be processed\nand stored in the system. The endpoint supports CSV and JSON file formats.\n\n**Rate Limits:**\n- 1 request/second per client\n- Simultaneous processing limit: 10 collections per client (can be adjusted upon request)\n","tags":["Collections"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CollectionUploadRequest"}}}},"responses":{"200":{"description":"Collection uploaded and created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUploadResponse"}}}},"400":{"description":"Bad request - validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientPermissionsAndLimit"},"422":{"description":"Unprocessable Entity - validation errors in collection data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Get collection by ID
> Retrieve a collection by its ID. Returns collection details and error information if present.
```json
{"openapi":"3.0.3","info":{"title":"Dataset Upload API","version":"1.0.0"},"servers":[{"url":"https://api.pixyle.ai/main/v1"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication"}},"schemas":{"CollectionDetailResponse":{"$ref":"#/components/schemas/CollectionDetail"},"CollectionDetail":{"allOf":[{"$ref":"#/components/schemas/CollectionBase"},{"type":"object","properties":{"error_count":{"type":"integer","description":"Number of errors in the collection"},"errors":{"type":"array","description":"List of errors for products in the collection","items":{"$ref":"#/components/schemas/CollectionError"}}},"required":["error_count","errors"]}]},"CollectionBase":{"type":"object","properties":{"id":{"type":"integer","description":"Collection ID"},"name":{"type":"string","description":"Collection name"},"product_count":{"type":"integer","description":"Number of products in the collection"},"processed_products_percentage":{"type":"number","format":"float","description":"Percentage of processed products"},"verified_products_percentage":{"type":"number","format":"float","description":"Percentage of verified products"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","name","product_count","processed_products_percentage","verified_products_percentage","created_at","updated_at"]},"CollectionError":{"type":"object","properties":{"product_id":{"type":"integer","description":"Product ID"},"image_name":{"type":"string","description":"Name of the image with error"},"error_code":{"type":"integer","description":"Error code"},"error_message":{"type":"string","description":"Error message"}},"required":["product_id","image_name","error_code","error_message"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"Error code"}},"required":["error","code"]}},"responses":{"Unauthorized":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"CollectionNotFound":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/collections/{id}":{"get":{"summary":"Get collection by ID","description":"Retrieve a collection by its ID. Returns collection details and error information if present.\n","tags":["Collections"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"The ID of the collection to retrieve."}],"responses":{"200":{"description":"Collection details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDetailResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/CollectionNotFound"}}}}}}
```
## Delete collection by ID
> Delete a collection by its ID.
```json
{"openapi":"3.0.3","info":{"title":"Dataset Upload API","version":"1.0.0"},"servers":[{"url":"https://api.pixyle.ai/main/v1"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication"}},"schemas":{"DeleteResponse":{"type":"object","properties":{"message":{"type":"string","description":"Confirmation message for deletion"}},"required":["message"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"Error code"}},"required":["error","code"]}},"responses":{"Unauthorized":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientPermissions":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"CollectionNotFound":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/collections/{id}":{"delete":{"summary":"Delete collection by ID","description":"Delete a collection by its ID.\n","tags":["Collections"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"The ID of the collection that should be deleted."}],"responses":{"200":{"description":"The collection was successfully deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientPermissions"},"404":{"$ref":"#/components/responses/CollectionNotFound"}}}}}}
```
## Export processed products from a collection
> Stream an export file for the products in a collection.\
> \
> The response is a streamed file download with a \`Content-Disposition\` header set for attachment. The mimetype is based on the requested \`file\_type\`.
```json
{"openapi":"3.0.3","info":{"title":"Dataset Upload API","version":"1.0.0"},"servers":[{"url":"https://api.pixyle.ai/main/v1"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"Error code"}},"required":["error","code"]}},"responses":{"Unauthorized":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientPermissions":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"CollectionNotFound":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimitExceeded":{"description":"Too Many Requests - rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/collections/{id}/export/{file_type}":{"get":{"summary":"Export processed products from a collection","description":"Stream an export file for the products in a collection.\n\nThe response is a streamed file download with a `Content-Disposition` header set for attachment. The mimetype is based on the requested `file_type`.\n","tags":["Collections"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"The ID of the collection to export."},{"name":"file_type","in":"path","required":true,"schema":{"type":"string","enum":["csv","json","xlsx"]},"description":"The file type for the export."}],"responses":{"200":{"description":"Export file streamed successfully","headers":{"Content-Disposition":{"schema":{"type":"string"},"description":"Indicates file download with filename."}},"content":{"application/json":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad request - validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientPermissions"},"404":{"$ref":"#/components/responses/CollectionNotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Add products in existing collection
> This endpoint allows you to add products in a existing collection. The endpoint supports CSV and JSON file formats.\
> \
> \*\*Rate Limits:\*\*\
> \- 1 request/second per client\
> \- Simultaneous processing limit: 10 collections per client (can be adjusted upon request)
```json
{"openapi":"3.0.3","info":{"title":"Dataset Upload API","version":"1.0.0"},"servers":[{"url":"https://api.pixyle.ai/main/v1"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication"}},"schemas":{"CollectionUploadRequest":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The dataset file to upload (CSV or JSON)"}},"required":["file"]},"CollectionUpgradeResponse":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the collection"},"name":{"type":"string","description":"The name of the collection"},"product_count":{"type":"integer","description":"Number of products/listings in the collection"},"image_count":{"type":"integer","description":"Number of images in the collection"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the collection was created"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the collection was last updated"}},"required":["id","name","product_count","image_count","created_at","updated_at"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"Error code"}},"required":["error","code"]}},"responses":{"Unauthorized":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientPermissionsAndLimit":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"CollectionNotFound":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimitExceeded":{"description":"Too Many Requests - rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/collections//products":{"post":{"summary":"Add products in existing collection","description":"This endpoint allows you to add products in a existing collection. The endpoint supports CSV and JSON file formats.\n\n**Rate Limits:**\n- 1 request/second per client\n- Simultaneous processing limit: 10 collections per client (can be adjusted upon request)\n","tags":["Collections"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CollectionUploadRequest"}}}},"responses":{"200":{"description":"Collection uploaded and created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUpgradeResponse"}}}},"400":{"description":"Bad request - validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientPermissionsAndLimit"},"404":{"$ref":"#/components/responses/CollectionNotFound"},"422":{"description":"Unprocessable Entity - validation errors in collection data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```