There are situations where you may need to upload a file client side instead of server side, but doing so might risk exposing an API key. To solve this you can create a presigned upload URL on the server and then pass it to the client for it to be consumed. Creating signed upload URLs can be done with either the Files SDK or the API, and you can designate how long the URL is valid for, how large the file can be, the type of file allowed, or extra metadata like a name and keyvalues. For a more robust example, check out our guides on Hono and React!

Hono Guide

React Guide

​
Usage

Setting up a server side API endpoint might look something like this: 
import { type NextRequest, NextResponse } from "next/server";
import { pinata } from "@/utils/config"; // Import the Pinata SDK instance

export const dynamic = "force-dynamic";

export async function GET() {
  // Handle your auth here to protect the endpoint
  try {
    const url = await pinata.upload.public.createSignedURL({
      expires: 30, // The only required param
      mimeTypes: ["text/*"], // Optional restriction for certain file types
      maxFileSize: 5000000 // Optional file size limit
    })
    return NextResponse.json({ url: url }, { status: 200 }); // Returns the signed upload URL
  } catch (error) {
    console.log(error);
    return NextResponse.json({ text: "Error creating signed URL:" }, { status: 500 });
  }
}
Then back on the client side code, you can upload using the signed URL instead of the regular upload endpoint.
If you’re using the SDK you can use the .url() parameter on any of the upload methods and pass in the signed upload URL there. If you are using the API you can simply make the upload request using the signed URL as the endpoint.
const urlRequest = await fetch("/api/url"); // Fetches the temporary upload URL from your server
const urlResponse = await urlRequest.json(); // Parse response
const upload = await pinata.upload.public
  .file(file)
  .url(urlResponse.url); // Upload the file with the signed URL

​
Reference

Below are the availble parameters for presigned URLs

​
expires

  • Type: number
The number of seconds the signed URL should be valid for 
const url = await pinata.upload.public.createSignedURL({
	expires: 30,
});

​
name (Optional)

  • Type: string
Name for the file to be uploaded 
const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	name: "My Cool File"
});

​
mimeTypes (Optional)

  • Type: string[]
Specify allowed file mime types and prevent uploads from files that do not match. Accepts wildcard mime types as well. 
const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	mimeTypes: [
	  "image/*",
		"application/json"
	]
});

​
maxFileSize (Optional)

  • Type: number
Restrict upload to a specified file size in bytes 
const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	maxFileSize: 50000 // 50kb
});

​
groupId (Optional)

  • Type: string
The target groupId the file would be uploaded to 
const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	groupId: "ad4bc3bf-8794-49e7-94ff-fea1ce745779"
});

​
keyvalues (Optional)

  • Type: Record<string, string>
Keyvalue pairs for the uploaded file 
const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	keyvalues: {
	  env: "prod"
	}
});

​
date (Optional)

  • Type: number
A UNIX timestamp of the date a URL is signed 
const date = Math.floor(new Date().getTime() / 1000);
//date: 1724943711

const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	date: date
});