What the Foldr API Can Do for Developers
The Foldr developer API lives at /api/v1 and is designed for developers who need file hosting baked into their workflows. It supports programmatic file uploads, bulk uploads, permanent link generation, and metadata control — all over standard HTTP.
Beyond simple uploads, the API gives you access to features like password-protected links, self-destructing links with expiration dates, and direct embed URLs for images, video, and audio. These aren't bolt-ons; they're first-class API parameters you can set on every upload.
Foldr also ships an MCP (Model Context Protocol) server alongside the REST API, which means you can connect it directly to AI tools like Claude Desktop or Cursor. If you work in AI-assisted environments, this opens up file handling as a native capability inside your editor or chat interface.
Authentication: Getting Your API Credentials
Every request to the Foldr file upload API requires an API key. You generate this from your Foldr account dashboard. Keep it in an environment variable — never hardcode it into source files you'll commit to version control.
Pass your key in the Authorization header as a Bearer token: `Authorization: Bearer YOUR_API_KEY`. This applies to every endpoint, whether you're uploading a single file, checking upload status, or deleting a stored file.
Free-tier accounts can make API calls, but the 2GB per-file limit and storage caps apply. If you're building a production integration that needs more headroom, a Pro account gives you 20GB of permanent storage and higher throughput limits — worth considering before you architect around the free tier.
Your First Programmatic File Upload: A Step-by-Step Request
The core upload endpoint accepts a multipart/form-data POST request. At minimum, you need the file itself. The API returns a JSON response containing the permanent download URL, a unique file ID, and metadata like file size and MIME type.
Here's what a minimal upload looks like using curl: ```bash curl -X POST https://foldr.space/api/v1/upload \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@/path/to/your/file.pdf" ``` The response will include a `url` field — that's your permanent link. It never expires unless you explicitly set an expiration.
In Python, the same request uses the `requests` library: ```python import requests with open('report.pdf', 'rb') as f: response = requests.post( 'https://foldr.space/api/v1/upload', headers={'Authorization': 'Bearer YOUR_API_KEY'}, files={'file': f} ) data = response.json() print(data['url']) # Your permanent download link ``` This pattern works the same way in Node.js with `form-data` and `axios`, or in any language that supports multipart HTTP requests.
One thing to note: the API responds synchronously for files within the size limit. You don't need to poll a job queue — the permanent URL is ready the moment the upload completes.
Controlling Access: Passwords, Expiry, and Embed URLs
A raw upload with a permanent link is useful, but the API becomes much more powerful when you layer on access controls. You can add a password to any upload by including a `password` field in your multipart form data. Anyone who visits the link will be prompted to enter it before downloading.
For files that should disappear after a set time, include an `expires_at` parameter formatted as an ISO 8601 datetime string. After that timestamp, the link returns a 404. This is useful for temporary credentials, one-time reports, or any content that shouldn't live forever.
If you're uploading images, video, or audio that you want to embed directly in a webpage or app, the API response includes an `embed_url` alongside the standard download URL. The embed URL streams the file directly, making it straightforward to drop into an `<img>`, `<video>`, or `<audio>` tag without any extra proxying on your end.
Bulk Uploads and Handling Multiple Files
When you need to upload dozens or hundreds of files at once, making individual requests isn't practical. The Foldr API supports bulk uploads, letting you send multiple files in a single request. The response returns an array of objects, one per file, each with its own permanent URL and metadata.
For very large batches, it's still good practice to chunk your uploads — say, 10 to 20 files per request — and implement basic retry logic with exponential backoff. Network hiccups happen, and a simple retry loop will handle the vast majority of transient errors without any manual intervention.
If you're orchestrating bulk uploads as part of a larger pipeline — for example, processing a folder of assets and distributing the links via email or Slack — you'll likely want to pair the API with an automation tool. Foldr's integrations with Zapier, n8n, and Make.com make this kind of multi-step workflow straightforward to set up without writing a full custom backend.
Integrating the API into Automations and No-Code Tools
Not every programmatic file upload needs to be written in code. Foldr's integrations page covers connections to Zapier, n8n, Make.com, and 45+ MCP-compatible tools, many of which expose the upload API through a visual interface. This is genuinely useful for teams where not everyone is a developer.
A common pattern: a form submission triggers a Zapier workflow that uploads an attachment to Foldr and then sends the permanent link back to the submitter. The whole thing takes maybe 15 minutes to set up and requires zero server management on your end.
For developers working in AI-native environments, the MCP server integration with Claude Desktop and Cursor is worth exploring. You can instruct your AI assistant to upload a file and return the link as part of a larger task — file storage becomes a tool call, not a manual step.
Choosing the Right Plan for API-Heavy Usage
The free tier works well for experimentation and low-volume integrations. You can upload files up to 2GB each, get permanent links with no account required, and hit the API without paying anything. This is a reasonable starting point for personal projects or testing an integration before committing.
If you're building something in production, the Pro plan is worth a serious look. You get 20GB of permanent storage, swappable images (useful if an asset URL needs to stay the same but the file changes), plus the URL Shortener Pro and Bio Pro features. Pro is available as a one-time payment — $99 for one year or $149 for two — or as a recurring subscription if you prefer that model.
Teams with heavier storage needs should look at Foldr Spaces. The Basic tier gives 5GB of dedicated team storage, Standard gives 20GB, and Premium scales up to 100GB. Spaces are designed for collaborative environments where multiple people or services need access to the same stored files.
Common Pitfalls and How to Avoid Them
The most common mistake developers make is treating the permanent link as guaranteed indestructible without understanding the conditions that can affect it. If you set an `expires_at` on upload, that link will die on schedule — which is the intended behavior, but it trips people up when they forget they set it. Always store the expiry metadata alongside the URL in your own database.
Another frequent issue is file size mismatches. If your application allows user uploads that get forwarded to Foldr, validate file size on your end before making the API call. Sending an oversized file wastes time and returns an error your user will see.
Finally, don't skip error handling on the API response. A 200 status doesn't always mean the URL is ready — check for an `error` field in the JSON body as well. Wrapping your upload calls in proper try/catch blocks and logging failed responses will save you debugging time when something unexpected happens in production.
Frequently Asked Questions
Do I need an account to use the Foldr file upload API?
You need an account to generate an API key, which is required for all API requests. However, Foldr's free tier lets you sign up without a paid plan, upload files up to 2GB, and receive permanent download links at no cost. It's a practical way to test the API before committing to a paid plan.
Are the download links generated by the API truly permanent?
Yes — by default, links generated via the Foldr API never expire. The exception is if you explicitly pass an `expires_at` parameter when uploading, which creates a self-destructing link. If you don't set an expiration, the link stays live as long as your account is active.
Can I upload files larger than 2GB with the API?
The 2GB per-file limit applies to free-tier accounts. Pro and Spaces plans have higher limits appropriate for production use. If you're regularly uploading large assets programmatically, upgrading before you hit those limits will prevent unexpected failures in your pipeline.
How do I make an uploaded file embeddable directly in a webpage?
When you upload an image, video, or audio file via the API, the response includes both a standard download URL and a direct embed URL. Use the embed URL as the `src` attribute in your HTML tags — it streams the file directly without redirects. This works for all supported media types.
Can I use the Foldr API without writing code, through tools like Zapier?
Yes. Foldr has native integrations with Zapier, n8n, Make.com, and 45+ other tools, including MCP-compatible AI environments like Claude Desktop and Cursor. These let you trigger uploads, retrieve permanent links, and use file hosting as a step in no-code or low-code workflows without writing HTTP requests manually.
What happens to my files if I downgrade from Pro to the free tier?
Foldr's documentation covers account downgrade behavior — it's worth reviewing those terms before building a production system that depends on Pro-level storage. As a general best practice, always store your permanent URLs in your own database so you have a record regardless of account changes.
The fastest way to validate your setup is to run the curl command from this tutorial against your own API key and confirm you get a permanent URL back in the response. Once that works, you have a foundation you can build on — add access controls, wire it into your automation tool of choice, or start batching uploads. Start with the simplest case, get it working end to end, then add complexity.