File Transfer API Documentation

The transitspotter File Transfer API provides secure, encrypted file sharing with temporary access codes. All uploads are encrypted with AES-256-GCM and automatically deleted after expiration or download limits.

Authentication Required

Service API endpoints require a valid API key from the transitspotter auth system.

Quick Start

Get started in 3 simple steps:

  1. Generate an API key
  2. Make a POST request to upload a file or URL
  3. Share the generated transfer code with recipients

Service API Endpoints

These endpoints are designed for programmatic access and integration with other services.

POST /api/service/upload

Upload a file directly via multipart form data.

Headers

Header Value Required
X-API-Key Your transitspotter API key Yes
Content-Type multipart/form-data Yes

Form Data Parameters

Parameter Type Description Required
file File The file to upload Yes
maxFileSize Number Maximum file size in bytes (default: 25MB, admin: up to 1GB) No
maxDownloads Number Maximum number of downloads (default: 1, admin: up to 100) No
customCode String Custom 6-digit code (auto-generated if not provided) No

Response 201 Created

{
  "success": true,
  "code": "123456",
  "url": "https://transfer.transitspotter.com?code=123456",
  "fileName": "document.pdf",
  "fileSize": 1048576,
  "formattedSize": "1.00 MB",
  "contentType": "application/pdf",
  "maxDownloads": 1,
  "expiresAt": 1640995200000,
  "expiresIn": 604800
}

POST /api/service/url-upload

Upload a file by providing a URL to download it from.

Headers

Header Value Required
X-API-Key Your transitspotter API key Yes
Content-Type application/json Yes

JSON Body Parameters

Parameter Type Description Required
url String URL of the file to download and transfer Yes
maxFileSize Number Maximum file size in bytes (default: 25MB, admin: up to 1GB) No
maxDownloads Number Maximum number of downloads (default: 1, admin: up to 100) No
customCode String Custom 6-digit code (auto-generated if not provided) No

Request Example

{
  "url": "https://example.com/file.pdf",
  "maxFileSize": 52428800,
  "maxDownloads": 5,
  "customCode": "123456"
}

Response 201 Created

{
  "success": true,
  "code": "123456",
  "url": "https://transfer.transitspotter.com?code=123456",
  "fileName": "file.pdf",
  "fileSize": 2097152,
  "formattedSize": "2.00 MB",
  "contentType": "application/pdf",
  "maxDownloads": 5,
  "expiresAt": 1640995200000,
  "expiresIn": 604800
}

Public API Endpoints

These endpoints can be used without authentication for accessing transfers.

GET /api/verify/{code}

Verify a transfer code and get transfer information.

Parameters

Parameter Type Description
code String 6-digit transfer code

Response 200 OK

{
  "fileUploaded": true,
  "fileName": "document.pdf",
  "fileSize": 1048576,
  "maxFileSize": 26214400,
  "maxDownloads": 1,
  "downloads": 0,
  "isFolder": false
}

GET /api/download/{code}

Download the file associated with a transfer code.

Parameters

Parameter Type Description
code String 6-digit transfer code

Response

Returns the file as a binary download with appropriate headers for filename and content type.

Error Responses

All API endpoints return consistent error responses in JSON format:

{
  "error": "Error type",
  "details": "Detailed error message"
}

HTTP Status Codes

Code Description Example
200 Success Transfer information retrieved
201 Created File uploaded successfully
400 Bad Request Invalid parameters
401 Unauthorized Invalid or missing API key
404 Not Found Invalid transfer code
413 Payload Too Large File size limit exceeded
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred

Rate Limits

File Limits

User Role Max File Size Max Downloads Retention
User 25MB 1-10 7 days
Moderator 25MB 1-10 7 days
Admin Up to 1GB 1-100 7 days

Security Features

Integration Examples

JavaScript/Node.js

// Upload a file
const formData = new FormData();
formData.append('file', fileBlob);
formData.append('maxDownloads', '3');

const response = await fetch('https://transfer.transitspotter.com/api/service/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key-here'
  },
  body: formData
});

const result = await response.json();
console.log('Transfer URL:', result.url);

// Upload from URL
const urlResponse = await fetch('https://transfer.transitspotter.com/api/service/url-upload', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/file.pdf',
    maxDownloads: 5
  })
});

const urlResult = await urlResponse.json();
console.log('Transfer code:', urlResult.code);

Python

import requests

# Upload from URL
response = requests.post(
    'https://transfer.transitspotter.com/api/service/url-upload',
    headers={'X-API-Key': 'your-api-key-here'},
    json={
        'url': 'https://example.com/file.pdf',
        'maxDownloads': 5
    }
)

result = response.json()
print(f"Transfer code: {result['code']}")
print(f"Transfer URL: {result['url']}")

# Upload a file
files = {'file': open('document.pdf', 'rb')}
data = {'maxDownloads': '3'}

response = requests.post(
    'https://transfer.transitspotter.com/api/service/upload',
    headers={'X-API-Key': 'your-api-key-here'},
    files=files,
    data=data
)

result = response.json()
print(f"Transfer URL: {result['url']}")

cURL

# Upload a file
curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@/path/to/file.pdf" \
  -F "maxDownloads=3" \
  https://transfer.transitspotter.com/api/service/upload

# Upload from URL
curl -X POST \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/file.pdf","maxDownloads":5}' \
  https://transfer.transitspotter.com/api/service/url-upload

# Verify a transfer
curl https://transfer.transitspotter.com/api/verify/123456

# Download a file
curl -O https://transfer.transitspotter.com/api/download/123456

Support & Resources

📧

Email Support

support@transitspotter.com

Technical questions and assistance
🏠

Web Interface

transfer.transitspotter.com

Browser-based file transfers