# 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.

**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.

## How do permanent upload links work?

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](https://thelastapi.dev/blog/store-ai-generated-images-permanent-links).

## Uploading files from your server with `@vibiz/app`

If you are building a Node, Bun, Deno, or edge backend, install [@vibiz/app](https://thelastapi.dev/docs/app-sdk):

```bash
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](https://thelastapi.dev/docs/use-one).

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

```ts
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:

```bash
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:

```bash
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:

```bash
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`:

```bash
# 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:

| Category | Supported formats | Browser handling |
| --- | --- | --- |
| Images | PNG, JPEG, GIF, WebP, AVIF, HEIC, SVG | Served inline; SVG sandboxed as attachment |
| Video | MP4, WebM, QuickTime | Served inline with byte-range seeking |
| Audio | MP3, WAV, OGG, WebM, AAC, FLAC, M4A | Served inline with byte-range seeking |
| Documents | PDF, text, CSV, Markdown, JSON | PDF served inline; text and CSV sandboxed |
| Archives | ZIP, other binary files | Served 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`:

```ts
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:

```bash
# 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:

```bash
vibiz files rm file_01k94x2...
```

Or send an HTTP DELETE request with your app key:

```bash
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:

```ts
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](https://thelastapi.dev/blog/private-files-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](https://thelastapi.dev/docs/keys).

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](https://thelastapi.dev/blog/one-key-whole-app-stack), or reference the complete API routes on the [Files](https://thelastapi.dev/docs/files) documentation page.

Ready to build? Create your account at [thelastapi.dev/start](https://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.

---

Published 2026-11-15 · https://thelastapi.dev/blog/file-uploads-permanent-links
