Skip to content

Wickson API Quick Start Guide

Welcome to the Wickson API by Firespawn Studios! This guide will help you get started with our powerful vector storage and search platform. Follow these steps to create your account and begin utilizing our API services.

Creating Your Account

  1. Visit app.wickson.ai and click "Sign Up" or "Get Started"
  2. Choose your preferred sign-up method:
  3. Sign in with GitHub
  4. Sign in with Google
  5. Register with email
  6. Once registered, you'll be directed to your personal dashboard
  7. Add funds to your account (minimum $10) to enable billable API operations
  8. Find your API key in the dashboard under "API Keys"

Important Note About File Storage

The Wickson API does not store your original files. When you upload files, they are processed to extract vector embeddings and metadata, then the original file data is securely deleted. Your search results will contain rich metadata and content extracts, but you cannot download the original files you uploaded.

What Wickson API stores: * Vector embeddings for semantic search * Metadata (summaries, descriptions, entities, etc.) * Content extracts for search context * Not the original files themselves

Making Your First API Request

Let's get started with a simple example! The quickest way to see the Wickson API in action is to analyze a media file using the /v1/ai/analyze endpoint.

Analyzing Media

This endpoint allows you to submit any supported file and ask questions about its content.

Using cURL

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/your/document.pdf" \
  -F "query=What are the key points in this document?" \
  https://api.wickson.ai/v1/ai/analyze

Using Python

import requests

# Configuration
api_key = "YOUR_API_KEY"
file_path = "document.pdf"
query = "What are the key points in this document?"

# Send analysis request
with open(file_path, "rb") as file:
    response = requests.post(
        "https://api.wickson.ai/v1/ai/analyze",
        headers={"X-Api-Key": api_key},
        files={"file": file},
        data={"query": query}
    )

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

    # Print key information
    print(f"Analysis of: {result['media_info']['filename']}")
    print(f"Cost: ${result['processing_info']['cost']}")
    print(f"\nAnswer: {result['answer']['main_response']}")

    # Print insights if available
    if "insights" in result["answer"]:
        print("\nKey Insights:")
        for insight in result["answer"]["insights"]:
            print(f"- {insight['observation']}")
else:
    print(f"Error {response.status_code}: {response.text}")

Complete Workflow Tutorial

For a more comprehensive understanding, let's walk through the typical workflow of uploading, listing, and searching content.

Step 1: Upload Media

First, let's upload a document to the Wickson API:

Using cURL

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@/path/to/your/report.pdf" \
  -F "collection_id=financial_reports" \
  https://api.wickson.ai/v1/media

Using Python

import requests

# Configuration
api_key = "YOUR_API_KEY"
file_path = "report.pdf"
collection = "financial_reports"

# Upload file
with open(file_path, "rb") as file:
    response = requests.post(
        "https://api.wickson.ai/v1/media",
        headers={"X-Api-Key": api_key},
        files={"file": file},
        data={"collection_id": collection}
    )

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

    print(f"Uploaded: {result['file_details']['filename']}")
    print(f"Media ID: {result['media_id']}")
    print(f"Collection: {result['storage_info']['collection']}")
    print(f"Cost: ${result['balance_info']['cost']}")

    if "content_summary" in result and "summary" in result["content_summary"]:
        print(f"\nSummary: {result['content_summary']['summary']}")
elif response.status_code == 409:
    print("File already exists. Add force_overwrite=true to replace it.")
else:
    print(f"Error {response.status_code}: {response.text}")

Step 2: List Your Media

Now, let's view all media in our collection:

Using cURL

curl -X GET \
  -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.wickson.ai/v1/media?collection=financial_reports"

Using Python

import requests

# Configuration
api_key = "YOUR_API_KEY"
collection = "financial_reports"

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

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

    print(f"Found {pagination['total_items']} items in collection '{collection}'")

    # Display media items
    for item in items:
        print(f"\n- {item['id']} | {item['media_type']} | {item['file_details']['filename']}")

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

Step 3: Search Your Content

Finally, let's search for specific information across your uploaded content:

Using cURL

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "revenue growth in Q4",
    "search_type": "basic",
    "collection": "financial_reports",
    "config": {
      "max_results": 5,
      "min_similarity": 0.7
    }
  }' \
  https://api.wickson.ai/v1/search

Using Python

import requests

# Configuration
api_key = "YOUR_API_KEY"

# Prepare search request
search_data = {
    "query": "revenue growth in Q4",
    "search_type": "basic",
    "collection": "financial_reports",
    "config": {
        "max_results": 5,
        "min_similarity": 0.7
    }
}

# Execute search
response = requests.post(
    "https://api.wickson.ai/v1/search",
    headers={
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    },
    json=search_data
)

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

    # Print search information
    query = data["meta"]["query"]
    stats = data["meta"]["stats"]
    print(f"Search for: '{query}'")
    print(f"Found {stats['total_results']} results in {stats['query_time_ms']}ms")

    # Display results
    for i, result in enumerate(data["results"], 1):
        print(f"\n{i}. {result['metadata']['filename']} (Score: {result['score']:.2f})")
        print(f"   {result['relevance_explanation']}")
        if "summary" in result['metadata']['search_metadata']:
            print(f"   Summary: {result['metadata']['search_metadata']['summary']}")
else:
    print(f"Error {response.status_code}: {response.text}")

Batch Processing

For processing multiple files at once, use our batch processing capabilities:

Create Batch (using cURL)

curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@report1.pdf" \
  -F "file=@report2.pdf" \
  -F "collection_id=financial_reports" \
  https://api.wickson.ai/v1/batches

Create Batch (using Python)

import requests

# Configuration
api_key = "YOUR_API_KEY"
files_to_upload = ["report1.pdf", "report2.pdf", "report3.pdf"]
collection = "financial_reports"

# Use context managers to properly handle file resources
with open(files_to_upload[0], "rb") as f1, open(files_to_upload[1], "rb") as f2, open(files_to_upload[2], "rb") as f3:
    # Prepare files for multipart upload with opened files
    files = [
        ("file", (files_to_upload[0], f1)),
        ("file", (files_to_upload[1], f2)),
        ("file", (files_to_upload[2], f3))
    ]

    # Create batch request
    response = requests.post(
        "https://api.wickson.ai/v1/batches",
        headers={"X-Api-Key": api_key},
        files=files,
        data={"collection_id": collection}
    )

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

    print(f"Batch created: {batch_id}")
    print(f"Status: {result['status']}")
    print(f"Files: {result['total_items']}")
    print(f"Estimated completion: {result['estimated_completion']}")
    print(f"Cost: ${result['cost_estimate']['total']}")
else:
    print(f"Error {response.status_code}: {response.text}")

You can then check the status of your batch job:

Check Batch Status (using cURL)

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://api.wickson.ai/v1/batches/batch-xyz789

Check Batch Status (using Python)

import requests
import time

# Configuration
api_key = "YOUR_API_KEY"
batch_id = "batch-xyz789"

# Check batch status
response = requests.get(
    f"https://api.wickson.ai/v1/batches/{batch_id}",
    headers={"X-Api-Key": api_key},
    params={"include_job_details": True}
)

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

    # Display batch overview
    print(f"Batch: {data['batch_name']} ({data['batch_id']})")
    print(f"Status: {data['status'].upper()}")

    # Display progress information
    progress = data["progress"]
    print(f"Progress: {progress['percentage']:.1f}% ({progress['completed']} of {progress['total']} complete)")

    # Show error count if any
    if progress["failed"] > 0 and "error_summary" in data:
        print(f"\nErrors: {progress['failed']} files failed")
        for error in data["error_summary"]:
            print(f"  - {error['error_type']} ({error['count']} files): {error['resolution']}")
else:
    print(f"Error {response.status_code}: {response.text}")

Here's how to perform an advanced search across multiple collections:

Using Python

import requests

# Configuration
api_key = "YOUR_API_KEY"

# Create advanced search request across multiple collections
search_data = {
    "query": "impact of climate change on business",
    "search_type": "advanced",
    "collections": ["research", "financial_reports", "news"],
    "config": {
        "context_depth": 2,
        "max_results": 10
    },
    "filters": {
        "created_after": "2024-01-01T00:00:00Z"
    }
}

# Execute search
response = requests.post(
    "https://api.wickson.ai/v1/search",
    headers={
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    },
    json=search_data
)

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

    # Print search information
    print(f"Advanced search for: '{meta['query']}'")
    print(f"Found {meta['stats']['total_results']} results across {len(meta['collections']['searched'])} collections")
    print(f"Depth reached: {meta['cost']['depth_reached']}")
    print(f"Collections: {', '.join(meta['collections']['searched'])}")

    # Group results by collection for better organization
    collection_results = {}
    for result in data["results"]:
        collection = result["collection"]
        if collection not in collection_results:
            collection_results[collection] = []
        collection_results[collection].append(result)

    # Display results by collection
    for collection, results in collection_results.items():
        print(f"\nCollection: {collection} ({len(results)} results)")
        for result in results:
            print(f"- {result['metadata']['file_info']['filename']} (Score: {result['score']:.2f})")
            print(f"  {result['relevance_explanation']}")
else:
    print(f"Error {response.status_code}: {response.text}")

Next Steps

  • Explore Full Documentation: Visit our API Documentation for complete details on all endpoints.
  • Check our GitHub: See our GitHub repository for in-depth code examples demonstrating advanced semantic search and other awesome uses for the Wickson API.
  • Monitor Usage: Keep track of your usage and costs through your dashboard or the /v1/usage endpoint.

Supported Media Types

The Wickson API supports various media formats, including:

  • Documents: PDF, DOCX, TXT, MD, RTF
  • Images: JPG, PNG, WebP, BMP, TIFF
  • Video: MP4, MOV, AVI, MKV
  • Audio: MP3, WAV, FLAC, M4A
  • 3D Models: STL, 3MF, GLB, OBJ

and many more!

Pricing

  • Media Processing: $0.03 for processing + $0.01 for database I/O
  • Vector Storage: FREE ongoing storage for processed files
  • Basic Search: FREE
  • Advanced Search: $0.01 + $0.01 per depth
  • Media Analysis: $0.03 per query
  • LLM/AI Query: $0.01 per query + context

Need Help?

This site uses cookies to help us improve the overall documentation and browsing experience. By continuing to use this site, you agree to our Privacy Policy.