Get Media Item¶

This endpoint retrieves detailed information about a specific media item by its ID.

Endpoint¶

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

Request¶

Path Parameters¶

Parameter	Type	Description
`media_id`	String	Required. The unique identifier of the media item.

Query Parameters¶

Parameter	Type	Default	Description
`include_vectors`	Boolean	false	Include vector embeddings in the response.
`include_chunks`	Boolean	false	Include content chunks in the response.
`include_metadata`	Boolean	true	Include metadata in the response.

Headers¶

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

Example Request¶

# Get a specific document with content chunks
curl -X GET \
  "https://api.wickson.ai/v1/media/doc_b1e01882-a58c-5010-a13c-ceff0c564f15?include_chunks=true" \
  -H "X-Api-Key: YOUR_API_KEY"

Python Example¶

import requests

# Configuration
api_key = "YOUR_API_KEY"
media_id = "doc_b1e01882-a58c-5010-a13c-ceff0c564f15"

# Get media item details
response = requests.get(
    f"https://api.wickson.ai/v1/media/{media_id}",
    headers={"X-Api-Key": api_key},
    params={
        "include_chunks": True,
        "include_vectors": False,
        "include_metadata": True
    }
)

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

    # Display media information
    print(f"Media ID: {media['id']}")
    print(f"Type: {media['media_type']}")
    print(f"Filename: {media['file_info']['filename']}")

    # Display summary if available
    if "metadata" in media and "search" in media["metadata"]:
        print(f"Summary: {media['metadata']['search']['summary']}")

    # Display content chunks if requested and available
    if "content" in media and "chunks" in media["content"]:
        print(f"\nFirst content chunk: {media['content']['chunks'][0][:100]}...")
else:
    print(f"Error {response.status_code}: {response.text}")

Response¶

{
  "success": true,
  "message": "Media item retrieved successfully",
  "data": {
    "id": "doc_b1e01882-a58c-5010-a13c-ceff0c564f15",
    "media_type": "document",
    "file_info": {
      "filename": "research_paper.pdf",
      "size_bytes": 538064,
      "checksum": "3fbcec1c16cecd8166ae7a6f8a00b240db995bd5df1d8aced124acc91959c019",
      "page_count": 23,
      "processed_at": "2025-03-09T04:47:50.338189"
    },
    "collection": "research",
    "status": {
      "state": "completed",
      "processing_info": {
        "completed_at": "2025-03-09T04:47:54.784841",
        "duration_ms": 15873
      }
    },
    "storage": {
      "created_at": "2025-03-09T04:47:54.783840"
    },
    "metadata": {
      "search": {
        "summary": "This research paper examines the impact of deep learning on natural language processing, with a focus on transformer architectures and their applications in various domains.",
        "description": "A comprehensive analysis of transformer-based models in NLP, covering their evolution from BERT to more recent architectures, and evaluating their performance across multiple benchmarks.",
        "semantic_markers": {
          "categories": ["AI Research", "Computer Science", "NLP"],
          "emotions": ["Analytical", "Informative", "Technical"],
          "topics": ["Deep Learning", "Transformers", "NLP"]
        },
        "entities": {
          "people": ["John Smith", "Jane Doe"],
          "organizations": ["Research Institute", "University of Science"],
          "locations": ["Boston, MA", "San Francisco, CA"],
          "concepts": ["attention mechanisms", "self-supervision", "fine-tuning"]
        },
        "quality_metrics": {
          "clarity": 0.85,
          "completeness": 0.95,
          "relevance": 0.9,
          "technical": 0.92
        }
      },
      "modality": {
        "formatting": {
          "original_format": "pdf",
          "structure_type": "Research paper",
          "was_truncated": false
        },
        "structure": {
          "has_figures": true,
          "has_tables": true,
          "page_count": 23,
          "sections": [
            {
              "title": "Introduction",
              "level": 1,
              "content_type": "Overview of the research"
            },
            {
              "title": "Methodology",
              "level": 1,
              "content_type": "Research approach and techniques"
            }
          ]
        }
      }
    },
    "content": {
      "text": "Abstract: This paper examines the evolution and impact of transformer models...",
      "chunks": [
        "Abstract: This paper examines the evolution and impact of transformer models...",
        "Introduction: Since the introduction of the transformer architecture by Vaswani et al. (2017)...",
        "Methodology: We evaluated seven different transformer variants across three benchmark datasets..."
      ],
      "summary": "This research paper examines the impact of deep learning on natural language processing..."
    }
  },
  "metadata": {
    "retrieval_time": "2025-03-09T21:54:52.466986",
    "api_version": "v1",
    "included_vectors": false,
    "included_chunks": true
  },
  "timestamp": "2025-03-09T21:54:52.466986"
}

Response Content Notice¶

The response contains metadata, content extracts, and vectors (when include_vectors=true) from your processed media, but not the original file. The Wickson API permanently deletes original files after processing and only stores derived data like vectors and rich metadata. Original files cannot be downloaded or retrieved through the Wickson API - this keeps your files more secure and enables you to take advantage of powerful search capabilities without the complexity of managing your media files in (yet) another cloud storage system.

Response Fields¶

Media Item Data¶

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 including filename, size, and format-specific information.
`collection`	The collection this item belongs to.
`status`	Processing status and information.
`storage`	Information about when the item was stored.
`metadata`	Rich metadata extracted from the content (included when `include_metadata=true`).
`content`	Content information including full text and chunks (included when `include_chunks=true`).
`vectors`	Vector embeddings (included when `include_vectors=true`).

Media-Type Specific Fields¶

Different media types include specialized fields in their file_info and metadata:

Document Files¶

page_count: Number of pages
structure: Section hierarchy and document organization
formatting: Information about the document format and structure

Image Files¶

dimensions: Width and height in pixels
color_mode: RGB, CMYK, etc.
visual_attributes: Visual characteristics identified in the image

Video Files¶

duration: Length in seconds
resolution: Width x height
frame_rate: Frames per second
key_frames: Important frames with timestamps

Audio Files¶

duration: Length in seconds
sample_rate: Audio sample rate
channels: Mono, stereo, etc.
transcript: Transcribed content (when available)

3D Model Files¶

vertex_count: Number of vertices
material_count: Number of materials
dimensions: 3D dimensions

Error Responses¶

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

Example Error Response¶

{
  "success": false,
  "message": "Media item not found",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "details": {
      "resource_type": "media_item",
      "resource_id": "doc_b1e01882-a58c-5010-a13c-ceff0c564f15"
    }
  }
}

Usage Notes¶

Use include_chunks=true when you need to access the content text or chunks for display or further processing
Use include_vectors=true only when you need the vector embeddings for custom similarity operations
The metadata contains rich information about the content, including semantic analysis, entities, and quality metrics
For large files, consider using specific content chunks rather than the full text for better performance