thelastapi
Get started free

File uploads for your app, with permanent links

Upload files through one API and get an unguessable permanent URL back immediately, with zero bucket configuration or complex asset hosting setups.

On this page 8 sections

You can upload files directly through thelastapi and immediately receive an unguessable, permanent URL without configuring storage buckets or CDN policies. Every project includes Files out of the box, giving you an upload endpoint that accepts up to 50 MB per file and returns a link formatted as https://thelastapi.dev/f/<key>/<name>. The 32-character key cannot be guessed or enumerated, and the link never expires.

Whether you run an app on our hosting or connect an existing backend running elsewhere, you can handle avatars, receipts, product images, and customer attachments through one client. This guide covers how permanent file links work, the upload methods available in Node.js and HTTP, and how to manage your project's storage.

When your app uploads a file, thelastapi stores it in your project's drive and returns a public URL immediately:

Text
https://thelastapi.dev/f/Qm9x81k2mN4pL0vR3sT6wY9zB1cE4fH7/avatar.png

The 32-character token in the path ensures nobody can crawl or guess other files in your account. The filename at the end is retained so downloads and browser tabs show the correct title.

Because public URLs do not expire, you can safely store them in your database, render them inside standard HTML <img> tags, or drop them directly into emails and notifications. Content delivery is handled for you:

  • MIME types: Assets are served with their own content type and X-Content-Type-Options: nosniff.
  • Caching: Responses include an ETag for browser caching.
  • Media seeking: Audio and video files support Accept-Ranges: bytes, allowing players to scrub forward and backward smoothly.
  • Inline viewing: Images, video, audio, and PDF files serve with Content-Disposition: inline. Everything else serves as an attachment.

If you are using our AI endpoints to generate assets, those media files land in the exact same storage drive automatically. For more details on that workflow, see where to keep AI-generated images, with permanent links.

Uploading files from your server with @vibiz/app

If you are building a Node, Bun, Deno, or edge backend, install @vibiz/app:

Terminal
npm install @vibiz/app

Your backend needs only one secret: VIBIZ_APP_KEY. If your app runs on another host, you can use the storage API independently without using any of our other resources. Read more about standalone setups in use one service.

To upload a file, pass a Buffer, Uint8Array, or Blob to vibiz.files.upload:

TypeScript
import { vibiz } from '@vibiz/app';

// Example: handling a user profile photo upload
export async function handleAvatarUpload(userId: string, imageBuffer: Buffer, fileName: string) {
  const file = await vibiz.files.upload(imageBuffer, {
    name: fileName,
    contentType: 'image/png',
    folder: 'avatars',
  });

  // file.url is permanent: store it directly on your user record
  console.log('Permanent URL:', file.url);
  console.log('File ID:', file.id);

  return file.url;
}

The upload response returns a complete file object:

JSON
{
  "object": "file",
  "id": "file_01k94x2...",
  "environment": "production",
  "name": "avatar.png",
  "folder": "avatars",
  "content_type": "image/png",
  "kind": "image",
  "size": 245102,
  "width": 512,
  "height": 512,
  "duration_seconds": null,
  "source": "upload",
  "ai": null,
  "tags": [],
  "note": null,
  "private": false,
  "url": "https://thelastapi.dev/f/Qm9x81k2mN4pL0vR3sT6wY9zB1cE4fH7/avatar.png",
  "url_expires_at": null,
  "created_at": "2026-10-28T10:00:00.000Z"
}

If you do not specify a contentType, the service inspects the file bytes and the extension to assign the proper type automatically.

Uploading via HTTP or the CLI

If you write in Python, Go, Ruby, or shell scripts, you can upload directly via raw HTTP requests or the CLI.

Using curl with raw bytes

Send the file bytes in the request body with a Content-Type header and the file name in the query string:

Terminal
curl -X POST "https://thelastapi.dev/v1/app/files?name=invoice-1042.pdf" \
  -H "Authorization: Bearer $VIBIZ_APP_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary "@invoice-1042.pdf"

You can also use standard multipart/form-data uploads:

Terminal
curl -X POST "https://thelastapi.dev/v1/app/files" \
  -H "Authorization: Bearer $VIBIZ_APP_KEY" \
  -F "file=@receipt.jpg"

Importing from an external URL

If a file already exists on the public web, you can pull it straight into your drive without streaming the bytes through your laptop or application server:

Terminal
curl -X POST "https://thelastapi.dev/v1/projects/prj_123/files/import" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/assets/logo.png", "name": "imported-logo.png", "folder": "brand"}'

Uploading via the CLI

During development or deployment scripts, use vibiz files upload:

Terminal
# Upload one or more files to a folder
vibiz files upload logo.png hero.jpg --folder brand

# Upload to the development environment
vibiz files upload test-data.csv --dev

Limits, rules, and supported formats

Each file can be up to 50 MB. Here is what the endpoint accepts:

CategorySupported formatsBrowser handling
ImagesPNG, JPEG, GIF, WebP, AVIF, HEIC, SVGServed inline; SVG sandboxed as attachment
VideoMP4, WebM, QuickTimeServed inline with byte-range seeking
AudioMP3, WAV, OGG, WebM, AAC, FLAC, M4AServed inline with byte-range seeking
DocumentsPDF, text, CSV, Markdown, JSONPDF served inline; text and CSV sandboxed
ArchivesZIP, other binary filesServed as download attachments

Executable scripts and raw markup formats—specifically HTML, JavaScript, and XML—are refused with a 400 invalid_request on the content-type parameter. This prevents your storage links from being abused for cross-site scripting or serving unmanaged web pages.

Storage is completely free during the beta. Total bytes stored are tracked daily under files.storage in your account usage metrics.

How to organize, search, and delete files

Once uploaded, you can query your drive using filters or free-text search.

Listing and finding files

From your app backend with @vibiz/app:

TypeScript
import { vibiz } from '@vibiz/app';

// Find the latest uploaded asset
const cover = await vibiz.files.latest({ type: 'image', source: 'ai' });

// List files matching specific filters
const files = await vibiz.files.list({
  type: 'image',
  source: 'upload',
});

From the terminal:

Terminal
# View newest files first
vibiz files

# Search by filename, tag, or prompt text
vibiz files search "invoice"

# Get the direct link to the newest image
vibiz files latest --type image

Deleting files

When a user deletes their account or updates an avatar, remove the old file using the CLI:

Terminal
vibiz files rm file_01k94x2...

Or send an HTTP DELETE request with your app key:

Terminal
curl -X DELETE "https://thelastapi.dev/v1/app/files/file_01k94x2..." \
  -H "Authorization: Bearer $VIBIZ_APP_KEY"

Once deleted, the physical bytes are cleared and the permanent URL immediately stops working, returning a 404.

What about files that should not be public?

Permanent links work well for marketing assets, user avatars, and public attachments. But sensitive records—like government tax forms, private invoices, or private customer exports—should not sit on an unauthenticated URL.

For sensitive files, upload with the private flag enabled:

TypeScript
const contract = await vibiz.files.upload(contractBuffer, {
  name: 'service-agreement.pdf',
  private: true,
});

When private: true is set, the API returns a signed URL that expires in one hour (url_expires_at). Attempting to load the bare link without its active cryptographic signature returns a 404. For a complete walkthrough of time-limited access and re-signing expired URLs, read our guide on private files with signed links.

Managing development versus production environments

Every project has two distinct storage environments: production and development.

  • Uploads made with your production app key (VIBIZ_APP_KEY) land in the production bucket.
  • Uploads made with a development key, or via vibiz dev and vibiz files upload --dev, land in your development storage drive.
  • AI models invoked with development keys also save their outputs to development files automatically.

This ensures that mock customer profiles, test data, and local script runs never clutter your live production assets or inflate production storage metrics. Both account owners and agents using limited keys can read, upload, and delete assets across both environments freely, as documented in our overview of keys and environments.

To explore combining file uploads with serverless Postgres, automated auth, and payment processing, check out one key for your whole app: the one-API stack for indie builders, or reference the complete API routes on the Files documentation page.

Ready to build? Create your account at thelastapi.dev/start to get your key and set up your first project.

Frequently asked questions

How long do permanent file URLs stay active?

Permanent file URLs never expire as long as the file remains in your project. If you delete the file by ID, the asset is removed and the link stops resolving immediately.

Can anyone list or browse all the files in my project through the public link?

No. Each link includes a unique 32-character random string that cannot be guessed or enumerated, and directory indexing is disabled.

What happens if I upload two files with the exact same name?

The system automatically appends a numeric suffix like `-2` or `-3` to the filename to avoid collisions, while generating a distinct random link key for each upload.

What is the maximum file size supported by the upload endpoint?

The upload endpoint accepts files up to 50 MB each across all supported image, video, audio, document, and archive formats.