List Media

This endpoint retrieves a paginated list of all your media items with powerful filtering capabilities.

Endpoint

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

Request

Headers

Header	Value	Description
X-Api-Key	YOUR_API_KEY	Required. Your API key for authentication.

Query Parameters

Parameter	Type	Default	Description
page	Integer	1	Page number for pagination.
page_size	Integer	20	Number of media items per page (max 100).
media_type	String	null	Filter by media type: document, image, video, audio, or model.
collection	String	null	Filter items by collection.
include_vectors	Boolean	false	Whether to include vector embeddings in the response.

Example Request

# List first page of documents in the "research" collection
curl -X GET \
  "https://api.wickson.ai/v1/media?page=1&page_size=10&media_type=document&collection=research" \
  -H "X-Api-Key: YOUR_API_KEY"

Python Example

import requests

# Configuration
api_key = "YOUR_API_KEY"

# List media items with filtering
response = requests.get(
    "https://api.wickson.ai/v1/media",
    headers={"X-Api-Key": api_key},
    params={
        "page": 1,
        "page_size": 10,
        "media_type": "document",
        "collection": "research"
    }
)

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

    print(f"Found {pagination['total_items']} items (showing page {pagination['page']} of {pagination['total_pages']})")

    # Display media items
    for item in data["items"]:
        media_type = item["media_type"]
        filename = item["file_info"]["filename"]
        created = item["storage"]["created_at"]

        print(f"- {item['id']} | {media_type} | {filename} | Created: {created}")

        # Show summary if available
        if "metadata" in item and "search" in item["metadata"] and "summary" in item["metadata"]["search"]:
            summary = item["metadata"]["search"]["summary"]
            print(f"  Summary: {summary[:100]}..." if len(summary) > 100 else f"  Summary: {summary}")
else:
    print(f"Error {response.status_code}: {response.text}")

Response

{
  "success": true,
  "message": "Media items retrieved successfully",
  "data": {
    "items": [
      {
        "id": "doc_b1e01882-a58c-5010-a13c-ceff0c564f15",
        "media_type": "document",
        "file_info": {
          "filename": "research_paper.pdf",
          "size_bytes": 538064,
          "checksum": "3fbcec1c16cecd8166ae7a6f8a00b240db995bd5df1d8aced124acc91959c019",
          "page_count": 23
        },
        "collection": "research",
        "storage": {
          "created_at": "2025-03-09T04:47:54.783840"
        },
        "metadata": {
          "search": {
            "summary": "This research paper examines...",
            "description": "A comprehensive analysis of...",
            "entities": {
              "people": ["John Smith", "Jane Doe"],
              "organizations": ["Research Institute", "University of Science"],
              "locations": ["Boston, MA", "San Francisco, CA"]
            },
            "semantic_markers": {
              "categories": ["Research", "Science", "Technology"],
              "topics": ["AI", "Machine Learning", "Neural Networks"]
            }
          },
          "modality": {
            "formatting": {
              "structure_type": "Research paper",
              "was_truncated": false
            }
          }
        }
      }
      // Additional media items...
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total_items": 42,
      "total_pages": 5,
      "has_next": true
    },
    "filters": {
      "applied": {
        "media_type": "document",
        "collection": "research"
      },
      "total_matching": 42
    }
  },
  "timestamp": "2025-03-09T21:54:51.466986"
}

Response Fields

Top-level fields

Field	Description
success	Boolean indicating whether the request was successful.
message	Human-readable description of the result.
data	Contains the media items list and pagination information.
timestamp	ISO 8601 timestamp of when the response was generated.

Data fields

Field	Description
items	Array of media item objects.
pagination	Information about the current page and total results.
filters	Information about the filters that were applied.

Media item fields

Field	Description
id	Unique identifier for the media item.
media_type	Type of media: document, image, video, audio, or model.
file_info	Details about the original file.
collection	The collection this item belongs to.
storage	Information about when the item was stored.
metadata	Structured metadata about the content (if include_metadata=true).
vectors	Vector embeddings (only if include_vectors=true).

Pagination fields

Field	Description
page	Current page number.
page_size	Number of items per page.
total_items	Total number of items matching the filters.
total_pages	Total number of pages available.
has_next	Whether there are more pages after the current one.

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters.
401	Unauthorized - Invalid API key.
403	Forbidden - Insufficient permissions.
429	Too Many Requests - Rate limit exceeded.
500	Internal Server Error - Something went wrong on our end.

Example Error Response

{
  "success": false,
  "message": "Invalid page parameter: must be a positive integer",
  "error": {
    "code": "INVALID_PARAMETER",
    "details": {
      "parameter": "page",
      "reason": "Must be a positive integer"
    }
  }
}

Usage Notes

• Use pagination to efficiently handle large collections of media items
• For faster responses, only request vectors when needed
• Create logical collections to organize your media items
• Filter by media type to quickly find specific content types
• The response includes powerful metadata that can be used for advanced searching and categorization

---