API Reference

Complete API reference for FileLens file preview generation service. FileLens provides multi-page document processing with download URL responses, supporting 450+ file formats including documents, images, and videos.

Base URL

The FileLens API is available at:

http://localhost:3000

For production deployments, replace localhost:3000 with your actual server address.

Authentication

Currently, no authentication is required. For production deployments, consider implementing API keys or JWT tokens for security.

Content Type

All API requests should use:

Content-Type: application/json

Endpoints

Health Check

Check service availability and status.

Endpoint: GET /health

Use this endpoint to verify that the FileLens service is running and healthy. Ideal for load balancer health checks and monitoring systems.

Request

GET

/health

curl http://localhost:3000/health

Response

{
  "status": "healthy",
  "timestamp": "2025-07-06T10:30:00Z",
  "service": "filelens",
  "version": "1.1.0"
}

Synchronous Preview Generation

Generate file previews immediately and return download URLs.

Endpoint: POST /preview

Generate previews synchronously for immediate use. Best for small files and real-time applications. Returns download URLs for all generated preview files.

Request Body

input (string, required): File input (URL, base64, or file path)
output_format (string, required): Output format: "jpg", "png", or "gif"
options (object, optional): Preview generation options

Request

POST

/preview

curl -X POST http://localhost:3000/preview \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/document.pdf",
    "output_format": "jpg",
    "options": {
      "width": 800,
      "height": 600,
      "quality": 90,
      "all_pages": true
    }
  }'

Response

{
  "success": true,
  "message": "Preview generated successfully",
  "preview_urls": [
    "/download/sync_1641312000_12345_def4_1.jpg",
    "/download/sync_1641312000_12345_def4_2.jpg",
    "/download/sync_1641312000_12345_def4_3.jpg"
  ],
  "total_pages": 3,
  "job_id": null
}

Asynchronous Preview Generation

Submit a preview generation job for processing.

Endpoint: POST /preview/async

Submit a job for asynchronous processing. Best for large files, many pages, or batch operations. Returns a job ID for status tracking.

Request Body

Same parameters as synchronous preview generation.

Request

POST

/preview/async

curl -X POST http://localhost:3000/preview/async \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/large-presentation.pptx",
    "output_format": "png",
    "options": {
      "width": 1920,
      "height": 1080,
      "quality": 95,
      "all_pages": true
    }
  }'

Response

{
  "success": true,
  "message": "Job created successfully",
  "preview_urls": null,
  "total_pages": null,
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Asynchronous Metadata Extraction

Submit a metadata extraction job for processing.

Endpoint: POST /metadata/async

Submit a job for asynchronous metadata extraction. Best for large image files or batch processing. Returns a job ID for status tracking.

Request Body

input (string, required): Image input (URL, base64, or file path)

Request

POST

/metadata/async

curl -X POST http://localhost:3000/metadata/async \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/large-photo.jpg"
  }'

Response

{
  "success": true,
  "message": "Metadata extraction job created successfully",
  "job_id": "550e8400-e29b-41d4-a716-446655440001"
}

Synchronous Metadata Extraction

Extract image metadata immediately and return detailed information.

Endpoint: POST /metadata

Extract metadata from images synchronously for immediate use. Returns comprehensive EXIF data, GPS coordinates, and image properties without generating previews.

Request Body

input (string, required): Image input (URL, base64, or file path)

Request

POST

/metadata

curl -X POST http://localhost:3000/metadata \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/photo.jpg"
  }'

Response

{
  "success": true,
  "message": "Metadata extracted successfully",
  "metadata": {
    "width": 3024,
    "height": 4032,
    "format": "jpeg",
    "color_space": "*color.YCbCr",
    "file_size": 2456789,
    "make": "Apple",
    "model": "iPhone 12 Pro",
    "date_time": "2023:10:15 14:30:22",
    "exposure_time": "1/120",
    "f_number": "f/1.6",
    "iso": "64",
    "focal_length": "5.1mm",
    "flash": "Flash did not fire",
    "orientation": "Horizontal (normal)",
    "gps": {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "altitude": 10.5
    }
  }
}

Unified Job Status Check

Check the status of any asynchronous job using the unified endpoint.

Endpoint: GET /status/{job_id} ⭐ Recommended

Check the processing status of any asynchronous job using the new unified endpoint. This endpoint works for both preview generation and metadata extraction jobs. Recommended for all new integrations.

Request

GET

/status/{job_id}

curl http://localhost:3000/status/550e8400-e29b-41d4-a716-446655440000

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "message": "Preview generated successfully",
  "result_urls": [
    "/download/result_550e8400-e29b-41d4-a716-446655440000_1641312000_1.png",
    "/download/result_550e8400-e29b-41d4-a716-446655440000_1641312000_2.png",
    "/download/result_550e8400-e29b-41d4-a716-446655440000_1641312000_3.png"
  ],
  "total_pages": 3,
  "progress": 100,
  "metadata": {
    "width": 3024,
    "height": 4032,
    "format": "jpeg"
  }
}

Legacy Job Status Check

Check the status of an asynchronous job using the legacy endpoint.

Endpoint: GET /preview/status/{job_id} 🔄 Legacy (Still Supported)

Check the processing status of an asynchronous job (both preview generation and metadata extraction). This endpoint is maintained for backward compatibility. Use the job ID returned from any async endpoint.

Note: This endpoint works identically to /status/{job_id} but is less future-proof. For new integrations, use the unified endpoint above.

Request

GET

/preview/status/{job_id}

curl http://localhost:3000/preview/status/550e8400-e29b-41d4-a716-446655440000

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "message": "Preview generated successfully",
  "result_urls": [
    "/download/result_550e8400-e29b-41d4-a716-446655440000_1641312000_1.png",
    "/download/result_550e8400-e29b-41d4-a716-446655440000_1641312000_2.png",
    "/download/result_550e8400-e29b-41d4-a716-446655440000_1641312000_3.png"
  ],
  "total_pages": 3,
  "progress": 100
}

File Download

Download generated preview files.

Endpoint: GET /download/{filename}

Download a generated preview file using the filename from the preview URLs. Returns the binary file content with appropriate MIME type headers.

Request

GET

/download/{filename}

curl http://localhost:3000/download/sync_1641312000_12345_def4_1.jpg \
  -o preview_page_1.jpg

Binary file content with appropriate MIME type headers

Request Parameters

Preview Options Object

Field	Type	Default	Description
`width`	integer	null	Output width in pixels (1-4000)
`height`	integer	null	Output height in pixels (1-4000)
`quality`	integer	85	JPEG quality (1-100)
`preview_time`	string	"00:00:01.000"	Video preview timestamp (HH:MM:SS.mmm)
`all_pages`	boolean	true	Generate previews for all pages (documents only)

Multi-Page Documents

Supported Document Types

PDF: All pages extracted and converted
Microsoft Office: DOC, DOCX, XLS, XLSX, PPT, PPTX
OpenDocument: ODT, ODS, ODP

Page Processing Behavior

When all_pages: true (default):

All pages are processed
Returns array of download URLs
Each URL corresponds to one page
Pages are numbered sequentially (1, 2, 3, ...)

When all_pages: false:

Only the first page is processed
Returns single-item array with one download URL

File Naming Convention

Generated files follow these patterns:

Synchronous requests:

sync_{timestamp}_{pid}_{hash}_{page_number}.{extension}

Asynchronous requests:

result_{job_id}_{timestamp}_{page_number}.{extension}

Examples:

sync_1641312000_12345_abc1_1.jpg (sync, page 1)
result_550e8400-e29b-41d4-a716-446655440000_1641312000_3.png (async, page 3)

Input Formats

URL Input

{
  "input": "https://example.com/document.pdf"
}

Base64 Input with Data URI

{
  "input": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PA..."
}

Raw Base64 Input

{
  "input": "JVBERi0xLjQKMSAwIG9iago8PA..."
}

Response Formats

Success Response

{
  "success": true,
  "message": "Description of operation",
  "preview_urls": ["array", "of", "download", "urls"],
  "total_pages": 5,
  "job_id": "uuid-for-async-jobs"
}

Error Response

{
  "success": false,
  "message": "Error description",
  "preview_urls": null,
  "total_pages": null,
  "job_id": null
}

Job Status Values

Status	Description
`pending`	Job created but not started
`processing`	Job is currently being processed
`completed`	Job finished successfully
`failed`	Job failed with error

Error Handling

HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid input parameters
404	Not Found - Job ID or file not found
422	Unprocessable Entity - File processing failed
500	Internal Server Error

Error Types

Type	Description	Solution
`InvalidInput`	Malformed request data	Check request format
`DownloadFailed`	Unable to download from URL	Verify URL accessibility
`ProcessingFailed`	File conversion failed	Check file format and content
`JobNotFound`	Job ID doesn't exist	Verify job ID
`ExternalToolError`	System tool failed	Check service dependencies

Examples

PDF Multi-Page Preview

curl -X POST http://localhost:3000/preview \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/report.pdf",
    "output_format": "jpg",
    "options": {
      "width": 800,
      "height": 600,
      "quality": 90,
      "all_pages": true
    }
  }'

PowerPoint Async Processing

curl -X POST http://localhost:3000/preview/async \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/presentation.pptx",
    "output_format": "png",
    "options": {
      "width": 1920,
      "height": 1080,
      "all_pages": true
    }
  }'

Video Thumbnail Generation

curl -X POST http://localhost:3000/preview \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/video.mp4",
    "output_format": "jpg",
    "options": {
      "width": 1280,
      "height": 720,
      "preview_time": "00:02:30.000"
    }
  }'

Image Metadata Extraction

curl -X POST http://localhost:3000/metadata \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/photo.jpg"
  }'

Async Metadata Processing

curl -X POST http://localhost:3000/metadata/async \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/large-photo.jpg"
  }'