youtube-summarizer/docs/EXPORT_API.md

# Export API Documentation

## Overview

The YouTube Summarizer Export API provides comprehensive functionality for exporting video summaries in multiple formats with customizable templates and bulk operations.

## Features

### 🎨 Supported Export Formats
- **Markdown** (.md) - Clean, formatted text for documentation
- **PDF** (.pdf) - Professional documents with formatting and branding
- **HTML** (.html) - Responsive web pages with embedded styles
- **JSON** (.json) - Structured data with full metadata
- **Plain Text** (.txt) - Simple, readable text format

### 🛠️ Template System
- **Jinja2 Templates** - Full template engine support
- **Default Templates** - Pre-configured templates for each format
- **Custom Templates** - Create and manage your own templates
- **Template Variables** - Access to all summary data and metadata
- **Live Preview** - Preview templates with sample data

### 📦 Bulk Export
- **Multiple Formats** - Export to multiple formats simultaneously
- **ZIP Archives** - Organized folder structure in compressed archives
- **Organization Options**:
  - By format (markdown/, pdf/, etc.)
  - By date (2025-01-25/, 2025-01-26/, etc.)
  - By video (separate folder per video)

## API Endpoints

### Single Export

#### `POST /api/export/single`
Export a single summary to the specified format.

**Request Body:**
```json
{
  "summary_id": "abc123",
  "format": "markdown",
  "template": "default",
  "include_metadata": true,
  "custom_branding": {
    "company_name": "My Company",
    "primary_color": "#2563eb",
    "secondary_color": "#1e40af"
  }
}
```

**Response:**
```json
{
  "export_id": "uuid-1234",
  "status": "completed",
  "format": "markdown",
  "download_url": "/api/export/download/uuid-1234",
  "file_size_bytes": 2048,
  "created_at": "2025-01-26T12:00:00Z",
  "completed_at": "2025-01-26T12:00:01Z"
}
```

### Bulk Export

#### `POST /api/export/bulk`
Export multiple summaries to a ZIP archive.

**Request Body:**
```json
{
  "summary_ids": ["abc123", "def456", "ghi789"],
  "formats": ["markdown", "pdf"],
  "organize_by": "format",
  "include_metadata": true,
  "template": "default"
}
```

**Response:**
```json
{
  "export_id": "uuid-5678",
  "status": "processing",
  "created_at": "2025-01-26T12:00:00Z",
  "estimated_time_remaining": 30
}
```

### Export Status

#### `GET /api/export/status/{export_id}`
Check the status of an export operation.

**Response:**
```json
{
  "export_id": "uuid-5678",
  "status": "completed",
  "format": "zip",
  "download_url": "/api/export/download/uuid-5678",
  "file_size_bytes": 102400,
  "created_at": "2025-01-26T12:00:00Z",
  "completed_at": "2025-01-26T12:00:30Z"
}
```

### Download Export

#### `GET /api/export/download/{export_id}`
Download the exported file.

**Response:** File download (appropriate MIME type)

### List Exports

#### `GET /api/export/list`
List all export operations with pagination.

**Query Parameters:**
- `page` (default: 1) - Page number
- `page_size` (default: 10) - Items per page
- `status` (optional) - Filter by status

**Response:**
```json
{
  "exports": [...],
  "total": 42,
  "page": 1,
  "page_size": 10
}
```

### Available Formats

#### `GET /api/export/formats`
Get list of available export formats.

**Response:**
```json
{
  "formats": [
    {
      "format": "markdown",
      "name": "Markdown",
      "description": "Clean, formatted Markdown for documentation",
      "available": true
    },
    {
      "format": "pdf",
      "name": "PDF",
      "description": "Professional PDF with formatting and branding",
      "available": true,
      "requires_install": false
    }
  ]
}
```

## Template API

### List Templates

#### `GET /api/templates/list`
List all available templates.

**Query Parameters:**
- `template_type` (optional) - Filter by type (markdown, html, text)

**Response:**
```json
[
  {
    "id": "markdown_default",
    "name": "default",
    "description": "Default Markdown template",
    "type": "markdown",
    "variables": ["video_metadata", "summary", "key_points"],
    "is_default": true,
    "preview_available": true
  }
]
```

### Get Template

#### `GET /api/templates/{template_type}/{template_name}`
Get a specific template with details.

**Query Parameters:**
- `include_preview` (default: false) - Include preview with sample data

**Response:**
```json
{
  "id": "markdown_custom",
  "name": "custom",
  "description": "Custom Markdown template",
  "type": "markdown",
  "variables": ["video_metadata", "summary"],
  "is_default": false,
  "content": "# {{ video_metadata.title }}\n\n{{ summary }}",
  "preview": "# Sample Video Title\n\nThis is a sample summary..."
}
```

### Create Template

#### `POST /api/templates/create`
Create a new custom template.

**Request Body:**
```json
{
  "name": "my-template",
  "type": "markdown",
  "content": "# {{ video_metadata.title }}\n\n{{ summary }}",
  "description": "My custom template"
}
```

### Update Template

#### `PUT /api/templates/{template_type}/{template_name}`
Update an existing template.

**Request Body:**
```json
{
  "content": "# Updated: {{ video_metadata.title }}",
  "description": "Updated description"
}
```

### Delete Template

#### `DELETE /api/templates/{template_type}/{template_name}`
Delete a custom template.

### Validate Template

#### `POST /api/templates/validate`
Validate template syntax without saving.

**Request Body:**
```json
{
  "content": "# {{ video_metadata.title }}",
  "template_type": "markdown"
}
```

**Response:**
```json
{
  "valid": true,
  "variables": ["video_metadata"],
  "message": "Template syntax is valid"
}
```

## Frontend Components

### ExportDialog Component
Single export dialog with format selection and options.

```tsx
import { ExportDialog } from '@/components/ExportDialog'

<ExportDialog
  summaryId="abc123"
  videoTitle="My Video"
  trigger={<Button>Export</Button>}
/>
```

### BulkExportDialog Component
Bulk export dialog for multiple summaries.

```tsx
import { BulkExportDialog } from '@/components/BulkExportDialog'

<BulkExportDialog
  summaryIds={["abc123", "def456"]}
  trigger={<Button>Bulk Export</Button>}
/>
```

## Template Variables

Templates have access to the following variables:

### video_metadata
- `title` - Video title
- `channel_name` - Channel name
- `duration` - Video duration
- `published_at` - Publication date
- `view_count` - View count
- `like_count` - Like count
- `thumbnail_url` - Thumbnail URL

### summary_data
- `summary` - Main summary text
- `key_points` - Array of key points
- `main_themes` - Array of main themes
- `actionable_insights` - Array of actionable insights
- `confidence_score` - AI confidence score
- `quality_score` - Quality assessment score

### export_metadata
- `exported_at` - Export timestamp
- `exporter_version` - Exporter version
- `youtube_summarizer_version` - App version

### processing_metadata
- `model` - AI model used
- `processing_time_seconds` - Processing duration
- `tokens_used` - Token count
- `timestamp` - Processing timestamp

## Error Handling

All API endpoints return standardized error responses:

```json
{
  "detail": "Error message",
  "status_code": 400,
  "error_code": "INVALID_FORMAT"
}
```

Common error codes:
- `INVALID_FORMAT` - Unsupported export format
- `TEMPLATE_NOT_FOUND` - Template doesn't exist
- `EXPORT_NOT_FOUND` - Export ID not found
- `EXPORT_FAILED` - Export process failed
- `TEMPLATE_SYNTAX_ERROR` - Invalid template syntax

## Rate Limiting

Export operations are rate-limited to prevent abuse:
- Single exports: 60 per minute
- Bulk exports: 10 per minute
- Template operations: 100 per minute

## File Size Limits

- Single export: Maximum 10MB per file
- Bulk export: Maximum 100MB per ZIP archive
- Template size: Maximum 100KB

## Cache Duration

- Export files: Cached for 24 hours
- Export status: Cached for 1 hour
- Template previews: Cached for 5 minutes

## Security

- All downloads require valid export IDs
- Export IDs expire after 24 hours
- Templates are sanitized to prevent XSS
- File paths are validated to prevent directory traversal

---

*Last updated: 2025-08-26*