Requires
pinata 2.6.0 or later (npm i pinata@latest).Usage
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.folderis 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).
failedis empty,uploadedholds every file, andfolderis undefined. Nothing needs to be sent again: Pinata finishes the folder on its own, so get it byfolderIdlater for its CID. - The upload was cancelled with
signal: files not uploaded yet are infailedwith an error named"AbortError".
files is the array you uploaded: File[] or { path, file }[]):
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 }[]
webkitRelativePath (set for an <input webkitdirectory> selection), else from their name. In Node.js, or to choose the paths yourself, pass entries:
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
sent but not start. Errors thrown by onProgress are ignored.
concurrency (Optional)
- Type:
number - Default:
4
retries (Optional)
- Type:
number - Default:
3
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)
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
"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.
await matters: the upload starts only when it’s awaited.
refreshJwt (Optional)
- Type:
() => Promise<string | undefined> | string | undefined
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
group (Optional)
- Type:
string
groupId
keyvalues (Optional)
- Type:
Record<string, string>
cidVersion (Optional)
- Type:
"v0" | "v1"
key (Optional)
- Type:
string
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.