Skip to main content
Upload files (typically images) to Vercel Blob storage for use in notes and other content.

​
Endpoint

POST /api/upload

​
Authentication

This endpoint requires the BLOB_READ_WRITE_TOKEN environment variable to be configured on the server.

​
Request

​
Headers

​
x-vercel-filename
string
default:"file.txt"
The desired filename for the uploaded file
​
content-type
string
default:"text/plain"
The MIME type of the file being uploaded (e.g., image/png, image/jpeg)

​
Body

The request body should be the raw file content (binary data).

​
Response

​
url
string
The public URL where the uploaded file can be accessed
​
downloadUrl
string
Alternative download URL for the file
​
pathname
string
The path of the file in Vercel Blob storage
​
contentType
string
The content type of the uploaded file
​
contentDisposition
string
Content disposition header value

​
Examples

​
Upload an image

curl -X POST https://your-domain.com/api/upload \
  -H "x-vercel-filename: profile.png" \
  -H "content-type: image/png" \
  --data-binary @profile.png

​
Response example

{
  "url": "https://public.blob.vercel-storage.com/profile-abc123.png",
  "downloadUrl": "https://public.blob.vercel-storage.com/profile-abc123.png?download=1",
  "pathname": "profile-abc123.png",
  "contentType": "image/png",
  "contentDisposition": "inline; filename=\"profile.png\""
}

​
Error responses

​
Missing token

{
  "error": "Missing BLOB_READ_WRITE_TOKEN. Don't forget to add that to your .env file."
}
Status code: 401 Unauthorized

​
Implementation details

The upload endpoint:
  • Runs on Vercel’s Edge Runtime for optimal performance
  • Uses Vercel Blob storage with public access
  • Automatically constructs filenames based on content type
  • Returns immediately with the public URL
Files uploaded through this endpoint are publicly accessible. Do not upload sensitive information.

​
Use cases

  • Editor images: Upload images pasted or dropped into the rich text editor
  • Profile pictures: Store user avatar images
  • Note attachments: Upload files to include in notes
  • Media embeds: Host images and media for embedding

​
See also

Rich text editor

Learn how the editor uses this endpoint for image uploads

Environment variables

Configure BLOB_READ_WRITE_TOKEN

Build docs developers (and LLMs) love

Get started for freeTalk to us