List Collections¶

This endpoint retrieves a list of all collections associated with your account. Collections are logical groupings of media items that help organize your content. The response includes basic information about each collection, such as its ID, item count, and creation date.

Endpoint¶

GET https://api.wickson.ai/v1/media/collections

Request¶

Headers¶

X-Api-Key: Required. Your Wickson API key with read capability.

Example Request¶

curl -X GET \
  -H "X-Api-Key: YOUR_API_KEY" \
  https://api.wickson.ai/v1/media/collections

Python Example¶

import requests

# Configuration
api_key = "YOUR_API_KEY"

# List collections
response = requests.get(
    "https://api.wickson.ai/v1/media/collections",
    headers={"X-Api-Key": api_key}
)

# Process the response
if response.status_code == 200:
    data = response.json()["data"]

    print(f"Found {data['total_collections']} collections:")

    # Display each collection with its item count
    for collection_id in data["collections"]:
        details = data["collection_details"][collection_id]
        print(f"- {collection_id}: {details['item_count']} items, created {details['created_at']}")
else:
    print(f"Error {response.status_code}: {response.text}")

Response¶

Status Codes¶

Status Code	Description
200 OK	Collections retrieved successfully.
401 Unauthorized	Invalid or missing API key.
403 Forbidden	Insufficient API key permissions.
429 Too Many Requests	Rate limit exceeded.
500 Internal Server Error	An unexpected error occurred.

Body (JSON)¶

{
  "success": true,
  "message": "Collections retrieved successfully",
  "data": {
    "collections": ["default", "research_papers", "product_images", "training_videos"],
    "collection_details": {
      "default": {
        "item_count": 45,
        "created_at": "2024-12-01T15:30:45Z"
      },
      "research_papers": {
        "item_count": 17,
        "created_at": "2025-01-15T10:22:33Z"
      },
      "product_images": {
        "item_count": 32,
        "created_at": "2025-02-03T09:15:00Z"
      },
      "training_videos": {
        "item_count": 8,
        "created_at": "2025-03-01T14:40:12Z"
      }
    },
    "total_collections": 4
  },
  "metadata": {
    "api_version": "1.0.0"
  }
}

Response Fields¶

Collections Information¶

Field	Description
`collections`	Array of collection IDs available in your account.
`collection_details`	Object containing details for each collection.
`collection_details.[id].item_count`	Number of media items in the collection.
`collection_details.[id].created_at`	ISO 8601 timestamp indicating when the collection was created.
`total_collections`	Total number of collections in your account.

Usage Notes¶

The "default" collection is automatically created and contains all media items not explicitly assigned to other collections.
Collections are created implicitly when uploading media with a collection_id parameter.
Empty collections (with no media items) may not appear in this list.

Error Responses¶

In case of error, the response will follow this structure:

{
  "success": false,
  "message": "Error message describing what went wrong",
  "error": {
    "code": "ERROR_CODE",
    "details": {
      "specific": "error details",
      "request_id": "req_12345"
    }
  }
}

Common Error Scenarios¶

HTTP Status	Error Code	Description
401	INVALID_API_KEY	Invalid or missing API key
403	INSUFFICIENT_PERMISSIONS	API key lacks read capability
429	RATE_LIMIT_EXCEEDED	Too many requests in time period
500	PROCESSING_ERROR	Error retrieving collections