Batch Delete Media

This endpoint allows you to delete multiple media items in a single operation. It's designed for efficient cleanup of collections or removal of outdated content. The operation is performed atomically where possible.

Endpoint

DELETE https://api.wickson.ai/v1/media/batch

Request

Headers

• X-Api-Key: Required. Your Wickson API key.
• Content-Type: application/json

Body (JSON)

• media_ids: Required. Array of media item IDs to delete.
• reason (optional): String. Reason for deletion, for logging purposes.

Example JSON body:

{
  "media_ids": ["vec-123abc", "vec-456def", "vec-789ghi"],
  "reason": "outdated_content"
}

Example Request

curl -X DELETE \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "media_ids": ["vec-123abc", "vec-456def", "vec-789ghi"],
    "reason": "outdated_content"
  }' \
  https://api.wickson.ai/v1/media/batch

Python Example

import requests

# Configuration
api_key = "YOUR_API_KEY"
media_ids = ["vec-123abc", "vec-456def", "vec-789ghi"]

# Delete multiple media items
response = requests.delete(
    "https://api.wickson.ai/v1/media/batch",
    headers={
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    },
    json={
        "media_ids": media_ids,
        "reason": "outdated_content"
    }
)

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

    print(f"Deleted: {deleted['count']} items")
    print(f"Failed: {failed['count']} items")

    if failed["count"] > 0:
        for media_id, reason in failed["reasons"].items():
            print(f"- Failed to delete {media_id}: {reason}")
else:
    print(f"Error {response.status_code}: {response.text}")

Response

Status Codes

Status Code	Description
200 OK	Batch deletion processed successfully.
400 Bad Request	Invalid request parameters.
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": "Batch deletion completed: 3 deleted, 0 failed",
  "data": {
    "deleted": {
      "count": 3,
      "media_ids": ["vec-123abc", "vec-456def", "vec-789ghi"],
      "hd_vectors": 3,
      "ld_vectors": 3
    },
    "failed": {
      "count": 0,
      "media_ids": [],
      "reasons": {}
    }
  },
  "metadata": {
    "operation_id": "batch_delete_1234567890",
    "timestamp": "2025-03-09T12:34:56Z",
    "processing_time_ms": 234,
    "reason": "outdated_content"
  }
}

Response Fields

Operation Results

Field	Description
deleted.count	Total number of successfully deleted media items.
deleted.media_ids	Array of media IDs that were successfully deleted.
deleted.hd_vectors	Number of high-dimensional vectors deleted.
deleted.ld_vectors	Number of low-dimensional vectors deleted.
failed.count	Number of media items that failed to delete.
failed.media_ids	Array of media IDs that failed to delete.
failed.reasons	Map of media IDs to failure reasons.

Metadata

Field	Description
operation_id	Unique identifier for this batch deletion operation.
timestamp	ISO 8601 timestamp when the operation was completed.
processing_time_ms	Time taken to process the deletion request in milliseconds.
reason	The reason for deletion as provided in the request.

Limitations

• Maximum of 100 media IDs per batch deletion request.
• All specified media IDs must belong to the authenticated user.
• Deletion is permanent and cannot be undone.

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
400	MISSING_MEDIA_IDS	Required media_ids array is missing
400	INVALID_MEDIA_IDS	media_ids must be a non-empty array
400	BATCH_TOO_LARGE	Maximum 100 media IDs per batch deletion
401	INVALID_API_KEY	Invalid or missing API key
403	INSUFFICIENT_PERMISSIONS	API key lacks delete capability
429	RATE_LIMIT_EXCEEDED	Too many requests in time period
500	PROCESSING_ERROR	Error during deletion processing