Skip to main content
Upload a folder file by file. Each file is its own resumable upload, several files are sent at the same time, and each file is retried on its own, so large folders (many files, large files, or both) upload reliably. Progress events report when each file starts sending, has all its bytes stored, is registered, is retried or fails.
Requires pinata 2.6.0 or later (npm i pinata@latest).

Usage

folder() doesn’t support signed upload URLs, so in a browser it sends a JWT. Don’t ship your admin JWT: create a scoped, short-lived key on your server with keys.create(), pass it as pinataJwt, and renew it with refreshJwt.

Returns

The folder, with the CID that covers every file, and each file’s own CID.
files are in the order given. group_id and keyvalues are the ones requested. With is_duplicate, Pinata kept an earlier folder with the same content and removed this one, so its group and keyvalues may differ from the ones requested. A FolderUploadError means the folder did not complete:
  • Some files failed for good after their retries. The others stay in folder folderId, which Pinata finishes without the failed ones. folder is that folder (id, name, cid, is_duplicate?) when the SDK could ask for it (not after a cancel or an authentication failure).
  • Every file was uploaded but the folder couldn’t be finished (the final sync kept failing for about 5 minutes). failed is empty, uploaded holds every file, and folder is undefined. Nothing needs to be sent again: Pinata finishes the folder on its own, so get it by folderId later for its CID.
  • The upload was cancelled with signal: files not uploaded yet are in failed with an error named "AbortError".
To send the failed files again into the same folder (files is the array you uploaded: File[] or { path, file }[]):
Send them within 30 minutes when error.folder is undefined, and within 24 hours in any case (see folderId). With folder.is_duplicate, the folder folderId was removed: send every file again without folderId. A new folder is created by its first file, the smallest file at the top level, which is sent alone. If it’s refused for a reason of its own (its path, type or size), the next file tries. Without folderId, if it fails for any other reason, or 3 files in a row are refused for the same reason, nothing else is sent and that error is thrown (an AuthenticationError, NetworkError or other PinataError), not a FolderUploadError. With folderId, the SDK first asks the API whether that folder exists (one request). If it does, every file starts at once. If it doesn’t, or the SDK can’t tell, the folder is created by its first file sent alone, as for a new folder. When that first file stops the upload, the files not sent yet fail with its error, and the upload rejects with a FolderUploadError holding folderId. With folderId, unless the folder is known not to exist yet, files that fail for good also stop the others: once 3 in a row fail with the same status and reason, the files not sent yet fail with that error without being sent. Failures due to the file’s own size or path (HTTP 413, 414, 431, or a ValidationError) don’t count toward these 3. Refusals that every file may get, such as HTTP 400, 415 or 422 for a missing group or a folder no longer accepting files, do count. When Pinata refuses the JWT (401 or 403), the SDK calls refreshJwt if you gave it. Without it, the refused files fail with an AuthenticationError, and so do files not sent yet, until you set another JWT with pinata.setNewJwt().

Parameters

files

  • Type: File[] or { path: string; file: File }[]
File objects take their path from webkitRelativePath (set for an <input webkitdirectory> selection), else from their name. In Node.js, or to choose the paths yourself, pass entries:
The folder is named after the top directory all paths share (photos above). If they don’t all share one top directory, files go into a folder named folder_from_sdk, or the one set with name. Entry paths may use \ as a separator. Two files with the same path, or a path with empty, . or .. segments, throw a ValidationError before anything is sent. A file whose path contains % can’t be uploaded yet: it fails (in FolderUploadError.failed) and the other files go on. The folder name can’t contain /, \ or %.

onProgress (Optional)

  • Type: (event: FolderUploadEvent) => void
Called for every file event:
Each file’s events arrive in order. A retry whose bytes are all stored already only checks the file’s registration: it emits sent but not start. Errors thrown by onProgress are ignored.

concurrency (Optional)

  • Type: number
  • Default: 4
How many files send their bytes at the same time. Files whose bytes are stored wait for Pinata to register them without holding a slot. At most 8 times as many files (32 by default) are under way at once.

retries (Optional)

  • Type: number
  • Default: 3
How many times a file is sent again after a transient failure: no answer, or HTTP 408, 409, 423, 425, 429 or 5xx. The SDK waits 1 s, doubling up to 10 s, or as long as Pinata asks (Retry-After, up to 5 minutes). Some attempts don’t count: those made while the browser is offline, those refused while Pinata finishes an earlier upload of the same path, and those refused a JWT that refreshJwt replaced. Other refusals, such as an invalid file, fail the file at once. retries is also how many times the final folder sync is sent again. When every file was uploaded, the sync waits up to 5 minutes without counting while Pinata is rate limited. After some files failed, the sync is only a best effort: a single attempt, without waiting for Retry-After or rate limiting.

folderId (Optional)

  • Type: string (a UUID)
Add files to a folder uploaded with folder(). Pinata accepts new files into such a folder for 24 hours after its last upload. After that, and for folders uploaded in one request (fileArray, form data, /pinFileToIPFS), each file is refused and the upload rejects with a FolderUploadError. Give the files paths under the folder’s name (as FolderUploadError.failed[].path are), or set it with .name(). A file whose path is already in the folder replaces it. A value that isn’t a UUID throws a ValidationError.

signal (Optional)

  • Type: AbortSignal
Cancels the upload: requests under way are aborted, and files not uploaded yet fail with an error named "AbortError". Files already uploaded stay in the folder. The upload rejects with a FolderUploadError, or with a PinataError named "AbortError" if every file was uploaded and the folder was being finished.
The await matters: the upload starts only when it’s awaited.

refreshJwt (Optional)

  • Type: () => Promise<string | undefined> | string | undefined
Called when Pinata refuses the JWT (401 or 403) during the upload, the final folder sync included. Return a new JWT: the SDK uses it from then on, as with setNewJwt, and sends the refused requests again without counting them against retries. It’s called once per refused JWT, however many files that JWT failed. Without it, or when it returns nothing, the refused files fail with an AuthenticationError. Not used with .key().

name (Optional)

  • Type: string
Name of the folder, instead of the top directory the paths share

group (Optional)

  • Type: string
Upload to a specific group by passing in the groupId

keyvalues (Optional)

  • Type: Record<string, string>
Add optional keyvalues to the folder

cidVersion (Optional)

  • Type: "v0" | "v1"
CID version of the files and the folder

key (Optional)

  • Type: string
Upload using a secondary API key generated through keys.create(). refreshJwt isn’t used with key().
vectorize, url (signed upload URLs), car, streamable, peerAddress and waitForCid(false) are not supported for folder uploads. As options they are type errors; the builder methods throw a ValidationError before anything is sent.