Upload • Share • Auto-Delete.
Home Help Terms Privacy

Developer API

Base URL: https://tempfile.org/api

Overview

Our REST API enables developers to integrate temporary file hosting into their applications. Upload files programmatically, get instant download URLs, and leverage automatic deletion for secure temporary storage.

API Limits & Features

File Size: 100MB maximum per file

Rate Limit: 10 uploads per hour per IP

Retention: 1-48 hours automatic deletion

Authentication: None required

Supported Formats: All safe file types (malware scanning included)

1. Upload Local File

Endpoint: POST /api/upload/local

Content-Type: multipart/form-data

Parameters

Example Request

curl -X POST https://tempfile.org/api/upload/local \
  -F "[email protected]" \
  -F "expiryHours=24"

Response

{
  "success": true,
  "files": [
    {
      "id": "file_1725187234567_abc123def",
      "name": "document.pdf",
      "size": 2048576,
      "url": "https://tempfile.org/file_1725187234567_abc123def/",
      "expiryTime": 1725273634567
    }
  ],
  "message": "1 file(s) uploaded successfully"
}

2. Upload from URL

Endpoint: POST /api/upload/url

Content-Type: application/json

Parameters

Example Request

curl -X POST https://tempfile.org/api/upload/url \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/image.jpg",
    "customName": "my-image.jpg",
    "expiryHours": 6
  }'

Response

{
  "success": true,
  "file": {
    "id": "file_1725187234567_xyz789abc",
    "name": "my-image.jpg",
    "size": 1024000,
    "url": "https://tempfile.org/file_1725187234567_xyz789abc/",
    "expiryTime": 1725208834567
  }
}

3. Get File Information

Endpoint: GET /api/file/{fileId}

Example Request

curl https://tempfile.org/api/file/file_1725187234567_abc123de

Response

{
  "success": true,
  "file": {
    "id": "file_1725187234567_abc123def",
    "name": "document.pdf",
    "size": 2048576,
    "mimeType": "application/pdf",
    "uploadTime": 1725187234567,
    "expiryTime": 1725273634567,
    "exists": true,
    "downloadUrl": "/file_1725187234567_abc123de/download",
    "security": {
    - `hasWarning` (boolean): Whether file triggered security alerts
    - `warningLevel` (string): Risk level - "none", "low", "medium", "high"
    - `warningMessage` (string): Human-readable warning description
    - `suspiciousPatterns` (array): Detected patterns (e.g., [".exe", "eval("])
    }
  }
}

4. Get File Security Information

Endpoint: GET /api/file/{fileId}/security

Returns detailed security analysis including risk assessment, detected patterns, and safety recommendations.

Example Request

curl https://tempfile.org/api/file/file_1725187234567_abc123de/security

Response

{
      "success": true,
      "security": {
        "fileId": "file_1725187234567_abc123de",
        "fileName": "project-build.zip",
        "mimeType": "application/x-zip-compressed",
        
        "hasWarning": true,
        "suspiciousPatterns": [".exe", ".bat"],
        
        "hash": "a1b2c3d4e5f6789...",
        "size": 127133,
        
        "uploadType": "local",
        "uploadTime": 1725187234567,
        "clientIP": "172.71.130.xxx",
        
        "riskLevel": "medium",
        "recommendations": [
          "Scan file with antivirus before opening",
          "Verify file source is trustworthy",
          "Open in isolated/sandboxed environment if possible",
          "Extract archive in secure location and inspect contents before execution"
        ]
      }
    }

Security Fields

Risk Levels

Level Description Example Patterns
safe No security warnings detected Clean files like images, PDFs, documents
low Common development patterns eval(), exec() in scripts
medium Contains executable files .exe, .bat, .cmd in archives
high Potentially dangerous content vbscript:, shell_exec, root exploits
unknown Warning exists but pattern unclear Unclassified suspicious patterns

Best Practices for API Consumers

Example: Handling Security Warnings in Code

// JavaScript example
    async function downloadFile(fileId) {
      // Get security info first
      const securityResponse = await fetch(`/api/file/${fileId}/security`);
      const securityData = await securityResponse.json();
      
      if (!securityData.success) {
        console.error('Failed to get security info');
        return;
      }
      
      const { riskLevel, recommendations, hasWarning } = securityData.security;
      
      // Warn user if file has security concerns
      if (hasWarning) {
        const proceed = confirm(
          `Security Warning (${riskLevel.toUpperCase()} risk):\n\n` +
          recommendations.join('\n') +
          '\n\nDo you want to proceed with download?'
        );
        
        if (!proceed) return;
      }
      
      // Proceed with download
      window.location.href = `/api/file/${fileId}/download`;
    }

5. Delete File

Endpoint: DELETE /api/file/{fileId}

Example Request

curl -X DELETE https://tempfile.org/api/file/file_1725187234567_abc123def

Response

{
  "success": true,
  "message": "File deleted successfully"
}

6. Direct File Download

Endpoint: GET /{fileId}/download

Returns the actual file content with appropriate headers for download.

Example Request

curl -L https://tempfile.org/file_1725187234567_abc123def/download \
  -o downloaded_file.pdf

Error Responses

All endpoints return consistent error formats:

{
  "success": false,
  "error": "Descriptive error message"
}

Common Error Codes

Usage Examples

JavaScript/Node.js

// Upload file
const formData = new FormData();
formData.append('files', fileInput.files[0]);
formData.append('expiryHours', '24');

try {
  const response = await fetch('https://tempfile.org/api/upload/local', {
    method: 'POST',
    body: formData
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const result = await response.json();
  
  if (result.success) {
    console.log('Upload URL:', result.files[0].url);
    console.log('File ID:', result.files[0].id);
    console.log('Expires at:', new Date(result.files[0].expiryTime));
  } else {
    throw new Error(result.error);
  }
} catch (error) {
  console.error('Upload failed:', error.message);
}

Python

import requests

# Upload file
with open('document.pdf', 'rb') as f:
    files = {'files': f}
    data = {'expiryHours': '24'}
    response = requests.post(
        'https://tempfile.org/api/upload/local',
        files=files,
        data=data
    )
    
result = response.json()
print(f"Upload URL: {result['files'][0]['url']}")

PHP


$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://tempfile.org/api/upload/local',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'files' => new CURLFile('document.pdf'),
        'expiryHours' => '24'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_FOLLOWLOCATION => true
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if (curl_error($curl)) {
    echo "Error: " . curl_error($curl);
} else {
    $result = json_decode($response, true);
    if ($result && $result['success']) {
        echo "Upload URL: " . $result['files'][0]['url'];
    } else {
        echo "Upload failed: " . ($result['error'] ?? 'Unknown error');
    }
}

curl_close($curl);

Best Practices

Common Use Cases

Prohibited API Usage

  • Uploading copyrighted content without permission
  • Hosting malware, viruses, or malicious files
  • Adult content or inappropriate material
  • Automated bulk uploading or spam
  • Using the API to circumvent rate limits
  • Commercial usage without permission

Rate Limits & Fair Usage

Our API implements fair usage policies to ensure service quality for all users:

Rate limit headers are included in API responses:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1725190834

Security & Content Scanning

All files uploaded through the API are automatically:

Response Formats

All API responses use JSON format with consistent structure:

Success Response

{
  "success": true,
  "files": [...],     // For upload endpoints
  "file": {...},      // For single file operations
  "message": "..."    // Human-readable message
}

Error Response

{
  "success": false,
  "error": "Descriptive error message"
}

File URLs and Access

Uploaded files are accessible via multiple URL formats:

Integration Examples

Simple File Upload Widget

async function uploadFile(file) {
  const formData = new FormData();
  formData.append('files', file);
  formData.append('expiryHours', '24');
  
  try {
    const response = await fetch('/api/upload/local', {
      method: 'POST',
      body: formData
    });
    
    const result = await response.json();
    if (result.success) {
      return result.files[0].url;
    } else {
      throw new Error(result.error);
    }
  } catch (error) {
    console.error('Upload failed:', error);
    throw error;
  }
}

Batch File Processing

// Process multiple URLs
const urls = [
  'https://example.com/doc1.pdf',
  'https://example.com/doc2.pdf'
];

const uploadPromises = urls.map(url => 
  fetch('/api/upload/url', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ url, expiryHours: 12 })
  }).then(r => r.json())
);

const results = await Promise.all(uploadPromises);
const uploadedFiles = results
  .filter(r => r.success)
  .map(r => r.file.url);

Webhooks & Notifications

Currently, the API operates on a pull-based model. For file status updates:

Terms of Use

API usage is subject to our Terms of Service. Key points:

API Support & Feedback

Developer Support: [email protected]

Feature Requests: [email protected]

Bug Reports: [email protected]

Response Time: 24-48 hours

Include your use case and sample code when reporting issues for faster resolution.

Changelog

Version 1.0 (September 2025)

Version 1.5 (October 2025)

Version 1.7 (October 2025)

Files auto-delete • No tracking • Secure hosting