Archive Uploads

Upload archive files (ZIP, tar, tar.gz, etc.) with the archive_mode parameter to control how archives are processed.

archive_mode Parameter

Use archive_mode to control how archives are handled:

Mode	Value	Behavior
Extract	`extract` (default)	Server extracts contents, creates IPFS directory structure
Preserve	`preserve`	Archive uploaded as a single file

When to Use Each Mode

extract: Publishing websites, datasets, multi-file content where individual files need to be accessible
preserve: Backups, sharing archives directly, when you need the exact same file back

Supported Formats

ZIP (.zip)
TAR (.tar)
Compressed TAR (.tar.gz, .tar.bz2, .tar.xz)
Other archive formats supported by the server

CID Limitation

Unlike CAR files, archive uploads cannot return the CID before processing completes.

Why?

Archives must be downloaded and verified
Contents are extracted and re-chunked into IPFS blocks
Root CID is computed from the resulting IPLD graph

What This Means

	CAR Files	Archives
CID calculation	Client-side	Server-side
Known before upload	Yes	No
Processing time	Instant	Requires polling
Pre-computation	Possible	Not possible

POST Upload (≤100MB)

Use POST for simple archive uploads up to 100MB.

Endpoint

POST https://ipfs.pinner.xyz/api/upload

Query Parameters

Parameter	Type	Required	Description
`archive_mode`	`string`	No	`extract` (default) or `preserve`

Form Fields

Field	Type	Required	Description
`file`	`File`	Yes	The archive file
`name`	`string`	No	Custom display name

Examples

Extract contents (default):

curl -X POST "https://ipfs.pinner.xyz/api/upload?archive_mode=extract" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@archive.zip"

Preserve archive as single file:

curl -X POST "https://ipfs.pinner.xyz/api/upload?archive_mode=preserve" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@archive.zip"

With custom name:

curl -X POST "https://ipfs.pinner.xyz/api/upload?archive_mode=extract" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@website.zip" \
  -F "name=my-website"

Response

{
  "id": "12345",
  "cid": "bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq",
  "name": "archive.zip",
  "size": 1048576,
  "mimeType": "application/zip",
  "operationId": 12345
}

TUS Upload (>100MB)

Use TUS for large archives over 100MB.

Workflow

Create upload with archive_mode in metadata
Upload chunks
Finish upload
Poll for CID

Create Upload

# Create upload with extract mode
curl -X POST "https://ipfs.pinner.xyz/api/upload/tus" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Length: 524288000" \
  -H "Upload-Metadata: archive_mode ZXh0cmFjdA==" \
  -H "Content-Length: 0"

Upload Chunks

# Upload first chunk
curl -X PATCH "https://ipfs.pinner.xyz/api/upload/tus/abc123xyz" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Content-Type: application/offset+octet-stream" \
  -H "Upload-Offset: 0" \
  -H "Content-Length: 5242880" \
  --data-binary @chunk1.bin

Finish and Poll

# Finish upload
curl -X DELETE "https://ipfs.pinner.xyz/api/upload/tus/abc123xyz" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Tus-Resumable: 1.0.0"
 
# Poll for CID
curl "https://ipfs.pinner.xyz/api/operations/abc123xyz" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Error Handling

Common Errors

400 Bad Request:

{
  "error": "bad_request",
  "message": "Invalid archive format or corrupted file"
}

413 Content Too Large:

{
  "error": "payload_too_large",
  "message": "POST upload exceeds 100MB limit. Use TUS for larger files."
}

422 Unprocessable Entity:

{
  "error": "invalid_archive",
  "message": "Archive is corrupted or password-protected"
}