Mimetype API

A modern REST API for file type detection powered by Google Magika - a deep learning model achieving >99% accuracy across 350+ file types.

Features

• File Type Detection - Identify file types from binary content or URLs
• File Type Validation - Verify files match expected type(s)
• SSRF Protection - Secure URL fetching with comprehensive IP/hostname blocking
• OpenAPI Documentation - Interactive Swagger UI at /docs

Quick Start

# Install dependencies
npm install

# Start the server
npm start

# Or run in development mode with watch
npm run dev

The API will be available at http://localhost:3000

API Endpoints

Detection

Endpoint	Method	Description
/detect	POST	Detect file type from binary content
/detect-url?url=<url>	GET	Detect file type from a URL

Validation

Endpoint	Method	Description
/validate?types=<types>	POST	Validate binary content matches expected types
/validate-url?url=<url>&types=<types>	GET	Validate URL content matches expected types

Information

Endpoint	Method	Description
/types	GET	List all supported file types
/health	GET	Health check
/docs	GET	Interactive API documentation

Usage Examples

Detect file type

curl -X POST http://localhost:3000/detect \
  -H "Content-Type: application/octet-stream" \
  --data-binary @image.png

Response:

{
  "type": "png",
  "isText": false,
  "confidence": 0.99,
  "details": {
    "dlPrediction": "png",
    "overwriteReason": null
  }
}

Detect from URL

curl "http://localhost:3000/detect-url?url=https://example.com/image.png"

Validate file type

curl -X POST "http://localhost:3000/validate?types=png,jpeg,gif" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @image.png

Response:

{
  "valid": true,
  "detectedType": "png",
  "expectedTypes": ["png", "jpeg", "gif"],
  "confidence": 0.99
}

List supported types

curl http://localhost:3000/types

Response:

{
  "count": 353,
  "types": [
    { "label": "png", "isText": false },
    { "label": "javascript", "isText": true }
  ]
}

Configuration

Environment Variable	Default	Description
PORT	3000	Server port
HOST	0.0.0.0	Server host

Tech Stack

• Fastify - High-performance web framework
• Magika - Google's deep learning file type detection
• Node.js >= 22.0.0 - Runtime environment

Testing

npm test

License

MIT