---
title: "Upload a file to Walrus storage"
method: POST
path: "/v4/data/storage/upload"
tags: ["Storage API"]
---

# Upload a file to Walrus storage

`POST /v4/data/storage/upload`

/v4/data/storage/upload

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

Upload a file to [Walrus](https://walrus.space) 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`.

## Response `200`

Upload job created and staged successfully.

- WalrusStorageEnqueueResponse — Response returned immediately after a file is staged for Walrus upload.
  - `jobId` string, 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.
  - `filename` string, 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`).
  - `mimeType` string — MIME type detected from the uploaded file.
  - `sizeBytes` integer, required — Number of bytes the server received.
  - `blobId` string, required — Pre-computed Walrus blob ID (deterministic from bytes + filename). Safe to use for download URL construction before certification completes.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
- `403` — Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.
- `500` — Internal server error. There was an error on the server during the processing of the request.

---

[API](https://skmtc.net/tatum/apis/blockchain-data.md) · [All operations](https://skmtc.net/tatum/apis/blockchain-data/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tatum/blockchain-data/revisions/8622ee4b8fae/schema)