Sign in

v1

latestOpenAPI 3.1.02026-07-243035381.4 MB
Storage API

Upload a file to Walrus storage

/v4/data/storage/upload

Billed via Walrus on-chain storage fees — no standard API credits consumed per call.

Upload a file to Walrus decentralized storage. Files are staged in GCS and then certified on-chain by the Walrus worker asynchronously. The response immediately returns a jobId and a pre-computed blobId; poll GET /v4/data/storage/upload/{jobId} to track certification progress.

Epochs and renewals: Walrus storage is divided into epochs (approximately 2 weeks each). Files are stored for the platform default of ~4 epochs (~8 weeks) and are automatically renewed by Tatum before each epoch window closes. Renewal fees (SUI/WAL on-chain costs × your plan rate) are charged to your Walrus storage balance. To stop automatic renewal, call DELETE /v4/data/storage/upload/{jobId}.

  • Maximum file size: 50 MiB.
  • Only available on mainnet API keys.
  • If another active upload already exists with the same filename and size, the filename is automatically disambiguated (e.g. report (1).pdf) to avoid blob-id collisions on-chain.
  • Send the file as a multipart/form-data field named file.
post/v4/data/storage/upload

Response

Upload job created and staged successfully.

jobIdstring required

Unique identifier for the upload job. Use it to poll status.

status'PENDING' | 'UPLOADING' | 'CERTIFIED' | 'FAILED' required

Lifecycle status of a Walrus storage upload job.

filenamestring required

Stored file name. May differ from the original if the name was disambiguated to avoid a duplicate blob ID on-chain (e.g. report (1).pdf).

mimeTypestring

MIME type detected from the uploaded file.

sizeBytesinteger required

Number of bytes the server received.

blobIdstring required

Pre-computed Walrus blob ID (deterministic from bytes + filename). Safe to use for download URL construction before certification completes.

Example response

{
  "jobId": "68000000000000000000abcd",
  "status": "CERTIFIED",
  "filename": "report.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 1048576,
  "blobId": "mAlStJ4PAJaBuuHEUHotGheikLiTXpQagboGF43bY4s"
}