Add Items to Collection¶

This endpoint adds or moves media items to a specified collection. It allows for organizing your media by moving individual items or batches of items between collections. The operation is atomic - either all specified items are moved successfully, or none are moved.

Endpoint¶

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

Request¶

Headers¶

X-Api-Key: Required. Your Wickson API key with write capability.
Content-Type: Required. Must be application/json.

Path Parameters¶

collection_id: Required. The identifier of the collection to add items to. Use default to move items back to the default collection.

Request Body (JSON)¶

{
  "items": [
    "vec-3f72e4a7b916c054d32a851f",
    "doc_eb45a612-7895-52bd-a413-86f321c4e9ab",
    "img_9c16d3a5-4287-5319-b614-7a428ed09bcf"
  ]
}

Request Fields¶

Field	Type	Description
`items`	array	Required. List of media item IDs to add to the collection. Supports both vector IDs (starting with `vec-`) and media IDs (like `doc_`, `img_`, etc.).

Example Request¶

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      "vec-3f72e4a7b916c054d32a851f",
      "doc_eb45a612-7895-52bd-a413-86f321c4e9ab",
      "img_9c16d3a5-4287-5319-b614-7a428ed09bcf"
    ]
  }' \
  https://api.wickson.ai/v1/media/collections/research_papers/items

Python Example¶

import requests

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

# Items to add to the collection
items = [
    "vec-3f72e4a7b916c054d32a851f",
    "doc_eb45a612-7895-52bd-a413-86f321c4e9ab",
    "img_9c16d3a5-4287-5319-b614-7a428ed09bcf"
]

# Add items to collection
response = requests.post(
    f"https://api.wickson.ai/v1/media/collections/{collection_id}/items",
    headers={
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    },
    json={"items": items}
)

# Process the response
if response.status_code == 200:
    data = response.json()["data"]
    summary = data["summary"]
    print(f"Added items to '{data['collection_id']}' collection:")
    print(f"  {summary['moved']} items moved")
    print(f"  {summary['already_in_collection']} already in collection")

    # Print item type distribution
    if "items_by_type" in data:
        types = ", ".join(f"{k}: {v}" for k, v in data["items_by_type"].items())
        print(f"  Types: {types}")
else:
    print(f"Error {response.status_code}: {response.text}")

Response¶

Status Codes¶

Status Code	Description
200 OK	Items successfully added to collection.
400 Bad Request	Invalid request format or parameters.
401 Unauthorized	Invalid or missing API key.
403 Forbidden	Insufficient API key permissions.
404 Not Found	One or more items not found.
429 Too Many Requests	Rate limit exceeded.
500 Internal Server Error	An unexpected error occurred.

Body (JSON)¶

{
  "success": true,
  "message": "3 items successfully moved to collection 'research_papers'",
  "data": {
    "collection_id": "research_papers",
    "summary": {
      "total": 3,
      "succeeded": 3,
      "failed": 0,
      "already_in_collection": 1,
      "moved": 2
    },
    "items_by_type": {
      "document": 2,
      "image": 1
    }
  },
  "metadata": {
    "request_id": "collection_20250311_121530_4a8fb923",
    "operation": "move_to_collection",
    "collection_id": "research_papers",
    "item_count": 3
  }
}

Response Fields¶

Summary Information¶

Field	Description
`collection_id`	Identifier of the target collection.
`summary.total`	Total number of items processed in the request.
`summary.succeeded`	Number of items successfully processed (both moved and already in collection).
`summary.failed`	Number of items that failed to be moved (always 0 for successful requests).
`summary.already_in_collection`	Number of items that were already in the target collection.
`summary.moved`	Number of items that were actually moved to the target collection.
`items_by_type`	Breakdown of processed items by media type.

Usage Notes¶

Collection Creation: If the specified collection doesn't exist, it will be created automatically.
Default Collection: Use default as the collection ID to move items back to the default collection.
ID Compatibility: The endpoint accepts both vector IDs (starting with vec-) and media IDs (like doc_, img_, etc.).
Batch Size: Maximum batch size is 1000 items per request.
Atomic Operation: The operation is atomic - either all items are successfully processed or none are.
Idempotent Operation: Items already in the target collection are detected and reported without error.
Performance: For very large collections, consider making multiple smaller batch requests.

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": "collection_20250311_121530_4a8fb923"
    }
  }
}

Common Error Scenarios¶

HTTP Status	Error Code	Description
400	VALIDATION_ERROR	Invalid request format, empty items list, or invalid collection ID
400	BATCH_SIZE_EXCEEDED	More than 1000 items in a single request
401	INVALID_API_KEY	Invalid or missing API key
403	INSUFFICIENT_PERMISSIONS	API key lacks write capability
404	ITEMS_NOT_FOUND	One or more specified items don't exist or don't belong to you
429	RATE_LIMIT_EXCEEDED	Too many requests in time period
500	STORAGE_ERROR	Error moving items, transaction failure
500	PROCESSING_ERROR	Unexpected server error

GET /v1/media/collections - List all collections
GET /v1/media/collections/{collection_id} - Get collection details
DELETE /v1/media/collections/{collection_id} - Delete a collection
GET /v1/media - List media items (can be filtered by collection)
POST /v1/search - Search within collections