COLD FILES API DOCUMENTATION ============================ Base URL: https://coldfiles.dev Also histora.online but thats deprecated All responses are JSON unless otherwise specified. By the way, i used AI to create alot of the CSS. (and these docs, but i checked and changed them) You can get an api key by msging me on discord (fast response) or emailing me (i probably wont read it). ill likely give you one. NOTES ----- - All files are private (unlisted) by default - File IDs are unique identifiers that can be used to access files - Private codes, if set, must be provided as a query parameter when downloading (unsecure, i know. but if you need it secure then you have come to the wrong place) - IP information is provided via ip-api.com - Timestamps are in ISO 8601 format https://imgs.xkcd.com/comics/iso_8601.png - File sizes are in bytes (Unless changed by js) - Gzip compression is supported for both uploads and downloads. - For downloads/API: Send `Accept-Encoding: gzip` or `X-Compression: gzip` header. - For uploads: Send `Content-Encoding: gzip` or `X-Content-Compression: gzip` header. 1. FILE UPLOADs Endpoint: POST /upload description: post a file and receive a id/link Parameters (form-data): - file (required): The file to upload - expire_downloads (optional): Number of downloads before file is deleted - private_code (optional): Access code required to download (max 64 chars) Example Request: curl -X POST https://coldfiles.dev/upload \ -F "file=@myfile.zip" \ -F "expire_downloads=5" \ -F "private_code=secret123" Response: { "success": true, "file": "/uploads/filename.zip", "file_id": "ABC123DEF", "file_extension": ".zip" } Note: All files are private (unlisted) by default. 1.1 RAW FILE UPLOADs (Non-multipart) Endpoint: POST /upload Description: Upload a file by sending the raw bytes in the request body. Headers: - X-Filename (required): The name of the file (e.g., myfile.txt) - X-Expire-Downloads (optional): Number of downloads before file is deleted - X-Private-Code (optional): Access code required to download - X-Private (optional): Set to "true" for unlisted uploads (default: true) - Content-Type: Should NOT be multipart/form-data Example Request: curl -X POST https://coldfiles.dev/upload \ -H "X-Filename: test.txt" \ -H "Content-Type: text/plain" \ --data-binary "This is the file content" Response: Same as standard upload. 2. FILE DOWNLOAD ---------------- This is a little weird. So initally it was BASE/uploads/filename But then people would upload the same file name twice, so it had to be filename + 6 random characters + its original ext but that was gay, and weird, and it told you that the other file existed which was sub-optimal if you wanted it private. so now its just file IDs. eg, BASE/id BASE/id.png if you need the site (eg discord) to know what its getting into Endpoint: GET / GET / Description: Download a file directly Parameters: - code (optional query param): Access code if file is code-protected Example: /myfileid.zip?code=secret123 (Use any file extension, it literally dosent care) Response: Binary file content 3. FILE METADATA ---------------- Endpoint: GET /file/ Description: Get public metadata about a file without downloading it Parameters: - file_id (required): The file ID returned from upload Example Request: curl https://coldfiles.dev/file/ABC123DEF Response: { "success": true, "file_id": "ABC123DEF", "filename": "myfile.zip", "file_extension": ".zip", "file_size": 1024000, "uploaded_at": "2026-04-15T10:30:00", "is_private": true, "downloads": 0, "expiry": { "max_downloads": 5, "downloads_remaining": 5 }, "code_protected": true } Fields: - file_id: Unique identifier for the file - filename: Original filename - file_extension: File extension with dot - file_size: Size in bytes - uploaded_at: ISO 8601 timestamp of upload - is_private: Always true for Cold Files - downloads: Download count (omitted if expiry is set) - expiry: Expiration settings (if configured) - code_protected: True if private code is set 4. IP INFORMATION ----------------- Endpoint: GET /ip Description: Get detailed information about the client's IP address Endpoint: GET /ip/ Description: Get detailed information about a specific IP address Parameters: - ip_address (optional): The IP address to look up (if omitted, auto-detects client IP) Example Request: curl https://coldfiles.dev/ip curl https://coldfiles.dev/ip/8.8.8.8 Response: { "success": true, "ip": { "IPv4": "203.0.113.42", "IPv6": null }, "other_details": { "isp": "Example ISP", "organization": "Example Corp", "asn": { "number": "AS12345", "name": "EXAMPLE-NET" }, "estimated_location": { "city": "San Francisco", "state": "California", "state_code": "CA", "country": "United States", "country_code": "US", "continent": "North America", "continent_code": "NA", "zip": "94105", "timezone": "America/Los_Angeles", "offset": -800 }, "coordinates": { "latitude": 37.7749, "longitude": -122.4194 }, "connection": { "mobile": false, "proxy": false, "hosting": false }, "reverse_dns": "example.com" } } We dont talk about number 5. 5. LINK SHORTENER ----------------- Endpoint: POST /s Description: Shorten a URL Parameters (JSON): - url (required): The URL to shorten Example Request: curl -X POST https://coldfiles.dev/s \ -H "Content-Type: application/json" \ -d '{"url": "https://google.com/"}' Response: { "success": true, "id": "26sas", "link": "https://coldfiles.dev/s/26sas" } Endpoint: GET /s Description: Show a form to shorten a URL Endpoint: POST /s Description: Shorten a URL Parameters (JSON or Form): - url (required): The URL to shorten Example Request: curl -X POST https://coldfiles.dev/s \ -H "Content-Type: application/json" \ -d '{"url": "https://google.com/"}' Response: { "success": true, "id": "26sas", "link": "https://coldfiles.dev/s/26sas" } Endpoint: GET /s/ Description: Redirect to the original URL Example: https://coldfiles.dev/s/26sas 6. STORAGE INFORMATION ---------------------- Endpoint: GET /storage Description: Get disk usage statistics. (Looking into switching to s3 style, might be deprecated in future) Response: { "success": true, (lol) "total_gb": 1000, "used_gb": 250, "free_gb": 750, "percent_used": 25 } OPTIONAL AUTHENTICATION ----------------------- Redacted, retarded AI thinking i want people knowing about how the perms work lol. But some things to note, not every API key is built the same. some can bypass limits, some can shut the server down. some are inbetween :-3 For the retarded among us, (sus) Common HTTP Status Codes: - 200: Success - 400: Bad Request - 404: File Not Found - 429: Rate Limited - 500: Server Error (uh oh, if you did something right please be sure to DM me on discord.) RATE LIMITING ------------- Requests are rate limited to 20 per hour per IP address. API keys with bypass_rate_limit permission are not rate limited. When rate limited, you'll receive a 429 response with message: "Rate limit exceeded. Maximum 20 requests per hour."