Get Collection Details¶

This endpoint retrieves detailed information about a specific collection, including its media content distribution, creation dates, and usage statistics. It provides insights into the types of media stored in the collection and when they were added.

Endpoint¶

GET https://api.wickson.ai/v1/media/collections/{collection_id}

Request¶

Headers¶

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

Path Parameters¶

collection_id: Required. The identifier of the collection to retrieve details for.

Example Request¶

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

Python Example¶

import requests

# Configuration
api_key = "YOUR_API_KEY"
collection_id = "research_papers"

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

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

    # Display collection information
    print(f"Collection: {data['collection_id']}")
    print(f"Items: {stats['item_count']}")
    print(f"Date range: {stats['first_item_date']} to {stats['last_item_date']}")

    # Display media type distribution
    types = ", ".join(f"{k}: {v}" for k, v in stats["media_type_distribution"].items())
    print(f"Media types: {types}")
else:
    print(f"Error {response.status_code}: {response.text}")

Response¶

Status Codes¶

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

Body (JSON)¶

{
  "success": true,
  "message": "Collection 'research_papers' details retrieved successfully",
  "data": {
    "collection_id": "research_papers",
    "stats": {
      "item_count": 17,
      "first_item_date": "2025-01-15T10:22:33Z",
      "last_item_date": "2025-03-05T16:45:22Z",
      "media_type_distribution": {
        "document": 12,
        "image": 3,
        "video": 2
      }
    }
  },
  "metadata": {
    "api_version": "1.0.0"
  }
}

Response Fields¶

Collection Information¶

Field	Description
`collection_id`	Identifier of the collection.
`stats.item_count`	Total number of media items in the collection.
`stats.first_item_date`	ISO 8601 timestamp of the oldest item in the collection.
`stats.last_item_date`	ISO 8601 timestamp of the newest item in the collection.
`stats.media_type_distribution`	Object showing count of media items by type.

Usage Notes¶

The "default" collection exists automatically and contains all media items not explicitly assigned to other collections.
If the specified collection is empty or doesn't exist, a 404 Not Found error will be returned.
The media_type_distribution provides a breakdown of content by type (document, image, video, audio, model).

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
404	COLLECTION_NOT_FOUND	The specified collection doesn't exist
429	RATE_LIMIT_EXCEEDED	Too many requests in time period
500	PROCESSING_ERROR	Error retrieving collection details