The Examples/Help Endpoint¶

Overview¶

The Examples/Help endpoint provides helpful information about the Wickson API, including available endpoints, capabilities, pricing, and getting started resources. Provides a starting point for exploring the API and understanding what functionality is available.

Endpoint Details¶

URL: /v1/examples or /v1/help (both routes provide identical responses)
Method: GET
Authentication Required: Yes

Request Parameters¶

This endpoint does not require any parameters.

Response Format¶

The response is a JSON object with the following structure:

{
  "success": true,
  "message": "API documentation retrieved successfully",
  "data": {
    "api_info": {
      "name": "Firespawn AI API",
      "version": "v1",
      "description": "Vector processing, search, and AI analysis API",
      "documentation_url": "https://docs.wickson.ai",
      "support_email": "sales@firespawnstudios.net"
    },
    "endpoint_categories": {
      "system": { ... },
      "media": { ... },
      "search": { ... },
      "batch": { ... },
      "collections": { ... }
    },
    "pricing": { ... },
    "getting_started": { ... }
  },
  "metadata": {
    "version": "v1",
    "generated_at": "2025-03-09T15:30:45.123456Z",
    "content_type": "application/json"
  }
}

Response Fields¶

Top-Level Fields¶

Field	Type	Description
`success`	Boolean	Indicates if the request was successful
`message`	String	A human-readable message about the result
`data`	Object	Contains the API documentation
`metadata`	Object	Contains metadata about the response

`data` Object¶

The data object contains detailed API information organized into the following sections:

api_info: General information about the API
endpoint_categories: Organized list of all available endpoints
pricing: Current pricing information for API services
getting_started: Resources to help you start using the API

`endpoint_categories` Object¶

Each category contains: - A description of the category - A list of endpoints with paths, methods, and descriptions

Example category:

"media": {
  "description": "Media processing and management",
  "endpoints": [
    {"path": "/v1/media", "method": "POST", "description": "Upload and process media files"},
    {"path": "/v1/media", "method": "GET", "description": "List processed media items"},
    ...
  ]
}

Example Usage¶

Request¶

curl -X GET \
  https://api.wickson.ai/v1/examples \
  -H 'X-Api-Key: your_api_key_here'

Or using the alternative endpoint:

curl -X GET \
  https://api.wickson.ai/v1/help \
  -H 'X-Api-Key: your_api_key_here'

Python Example¶

import requests
import json

# Configuration
api_key = "YOUR_API_KEY"

# Get API documentation
response = requests.get(
    "https://api.wickson.ai/v1/help",  # or use "/v1/examples"
    headers={"X-Api-Key": api_key}
)

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

    # Print API information
    print(f"{api_info['name']} (v{api_info['version']})")
    print(f"{api_info['description']}")
    print(f"Documentation: {api_info['documentation_url']}")

    # Print endpoint categories
    print("\nAvailable Endpoints:")
    for category, info in data["endpoint_categories"].items():
        print(f"\n{category.upper()} - {info['description']}")
        for endpoint in info["endpoints"]:
            auth = " (no auth)" if endpoint.get("auth_required") is False else ""
            print(f"- {endpoint['method']} {endpoint['path']}{auth}: {endpoint['description']}")

    # Print pricing information
    print("\nPricing:")
    for service, price in data["pricing"].items():
        print(f"- {service}: {price}")

    # Print getting started information
    print("\nGetting Started:")
    for key, value in data["getting_started"].items():
        print(f"- {key}: {value}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Response¶

{
  "success": true,
  "message": "API documentation retrieved successfully",
  "data": {
    "api_info": {
      "name": "Firespawn AI API",
      "version": "v1",
      "description": "Vector processing, search, and AI analysis API",
      "documentation_url": "https://docs.wickson.ai",
      "support_email": "sales@firespawnstudios.net"
    },
    "endpoint_categories": {
      "system": {
        "description": "System status and API information",
        "endpoints": [
          {"path": "/health", "method": "GET", "description": "Check API health status", "auth_required": false},
          {"path": "/v1/status", "method": "GET", "description": "Get detailed system status and account information"},
          {"path": "/v1/usage", "method": "GET", "description": "Retrieve usage statistics and billing information"}
        ]
      },
      "media": {
        "description": "Media processing and management",
        "endpoints": [
          {"path": "/v1/media", "method": "POST", "description": "Upload and process media files"},
          {"path": "/v1/media", "method": "GET", "description": "List processed media items"},
          {"path": "/v1/media/{media_id}", "method": "GET", "description": "Get details for a specific media item"},
          {"path": "/v1/media/{media_id}", "method": "DELETE", "description": "Delete a media item"},
          {"path": "/v1/ai/analyze", "method": "POST", "description": "Perform AI analysis on media without storage"}
        ]
      },
      "search": {
        "description": "Vector search capabilities",
        "endpoints": [
          {"path": "/v1/search", "method": "POST", "description": "Perform vector search across your data"}
        ]
      },
      "batch": {
        "description": "Batch operations for processing multiple items",
        "endpoints": [
          {"path": "/v1/batches", "method": "POST", "description": "Create batch processing job"},
          {"path": "/v1/batches/{batch_id}", "method": "GET", "description": "Get batch status"},
          {"path": "/v1/batches/{batch_id}/state", "method": "PUT", "description": "Control batch state (cancel/pause)"},
          {"path": "/v1/batches/{batch_id}/results", "method": "GET", "description": "Get batch results"}
        ]
      },
      "collections": {
        "description": "Manage collections of media items",
        "endpoints": [
          {"path": "/v1/media/collections", "method": "GET", "description": "List all collections"},
          {"path": "/v1/media/collections/{collection_id}", "method": "GET", "description": "Get collection details"},
          {"path": "/v1/media/collections/{collection_id}", "method": "DELETE", "description": "Delete a collection and all its contents"}
        ]
      }
    },
    "pricing": {
      "storage": "FREE (includes vector embeddings + metadata)",
      "database_io": "$0.01 per operation",
      "media_processing": "$0.03 per file (varies by type)",
      "basic_search": "FREE",
      "advanced_search": "$0.01 per search + $0.01 per depth",
      "llm_queries_": "$0.01 per query + context",
      "rag_queries": "$0.03 per query"
    },
    "getting_started": {
      "documentation": "Visit https://docs.wickson.ai for detailed guides and examples",
      "authentication": "Include your API key in all requests with the X-Api-Key header",
      "examples": "Find code examples in our documentation or GitHub repository at https://github.com/firespawnstudios"
    }
  },
  "metadata": {
    "version": "v1",
    "generated_at": "2025-03-09T15:30:45.123456Z",
    "content_type": "application/json"
  }
}

Notes¶

This endpoint is designed to provide a high-level overview of the API capabilities
Use this as a starting point to explore available endpoints
For detailed documentation on specific endpoints, refer to the full documentation at https://docs.wickson.ai

Response Codes¶

Status Code	Description
200	Success
401	Unauthorized - API key is missing or invalid
403	Forbidden - API key lacks required 'read' capability
500	Server Error - Failed to generate documentation