TAtatum
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

Request

  • Base URL
    https://api.tatum.io
  • URL
    https://api.tatum.io/v4/data/storage/upload
  • Auth
    API key in header x-api-key

Request body multipart/form-data

filestring binary required

The file to upload (max 50 MiB).

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"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.