Web3 Storage Getting Started: API Keys and First Request (2026)

Getting started overview

Getting started with Web3 Storage involves a sequence of steps designed to integrate decentralized storage into your applications. The primary method of interaction is through its API, which supports various client libraries for common programming languages. This guide provides a focused overview of the initial setup, from account creation and API token generation to executing your first storage request.

Web3 Storage leverages the InterPlanetary File System (IPFS) for content addressing and the Filecoin network for persistent storage, providing a decentralized approach to data management. Understanding the core concepts of content addressing and decentralized identifiers can be beneficial for advanced use cases, as outlined by the W3C Decentralized Identifiers (DIDs) specification.

The following table summarizes the key steps:

Create an account and get keys

To begin using Web3 Storage, you must first create an account. A free tier is available, offering 1 TB of storage and 1 TB of bandwidth per month, which is suitable for initial development and testing. Account creation is a standard process involving email verification.

1. Navigate to the Web3 Storage homepage: Visit web3.storage.
2. Sign up: Click on the "Sign Up" or "Get Started" button and follow the prompts to create your account. This typically involves providing an email address and setting a password, followed by email verification.
3. Log in: Once your account is created and verified, log in to your dashboard.
4. Generate an API Token: Within your dashboard, locate the "API Tokens" section. Click "New token" to generate a unique API token. This token acts as your authentication credential for all API interactions. Keep this token secure, as it grants access to your storage and data. The official documentation provides a detailed guide on generating API tokens securely.

The generated API token is a bearer token, meaning it should be included in the Authorization header of your HTTP requests. For example, Authorization: Bearer YOUR_API_TOKEN.

Your first request

After obtaining your API token, you can make your first request to upload a file. Web3 Storage supports direct HTTP API calls and provides client libraries for JavaScript, Python, Go, and Rust. This example focuses on using the HTTP API with curl and a JavaScript example using the client library, which is a common approach for web-based decentralized applications.

Using the HTTP API with curl

To upload a file using the HTTP API, you will make a POST request to the /upload endpoint. Replace YOUR_API_TOKEN with your actual token and /path/to/your/file.txt with the path to the file you wish to upload.

curl -X POST \ 
  -H "Authorization: Bearer YOUR_API_TOKEN" \ 
  --data-binary "@/path/to/your/file.txt" \ 
  https://api.web3.storage/upload

A successful response will return a JSON object containing the Content ID (CID) of the uploaded file, which uniquely identifies the content on IPFS.

{
  "cid": "bafybeibzfs25q2f5j3gq2q3q2q3q2q3q2q3q2q3q2q3q2q3q2q3q2q3q2q3q2q3q2q3"
}

The CID is crucial for retrieving your data and sharing it within the IPFS network. For more details on content addressing, refer to the Cloudflare IPFS Gateway content addressing documentation.

Using the JavaScript Client Library

The JavaScript client library simplifies interaction with the Web3 Storage API. First, install the library:

npm install web3.storage

Then, you can use the following code to upload a file. This example assumes you are running in a Node.js environment or a browser with appropriate polyfills for file handling.

import { Web3Storage, File } from 'web3.storage'

async function getAccessToken () {
  // In a production environment, retrieve the token securely.
  // For demonstration, replace with your actual token.
  return 'YOUR_API_TOKEN'
}

async function storeFiles (files) {
  const token = await getAccessToken()

  if (!token) {
    console.error('A token is needed. You can create one on https://web3.storage')
    return
  }

  const client = new Web3Storage({ token })
  const cid = await client.put(files)
  console.log('Stored files with CID:', cid)
  return cid
}

// Example usage: Uploading a simple text file
async function uploadExample () {
  const textContent = 'Hello, Web3 Storage!'
  const fileName = 'hello.txt'
  const file = new File([textContent], fileName, { type: 'text/plain' })
  const cid = await storeFiles([file])
  console.log(`Access your file at https://${cid}.ipfs.w3s.link/${fileName}`)
}

uploadExample()

This script constructs a File object and uses the client.put() method to upload it. The returned CID can then be used to access the file via an IPFS gateway.

Common next steps

Once you have successfully uploaded your first file, several common next steps can enhance your Web3 Storage integration:

• Retrieve Data: Learn how to retrieve your stored data using the CID, either through IPFS gateways or directly via the API. The Web3 Storage documentation on retrieving files provides detailed instructions.
• Manage Files: Explore features for listing, managing, and deleting your stored content. This includes understanding content pinning and how it relates to Filecoin storage deals.
• Integrate with DApps: Incorporate Web3 Storage into your decentralized applications (DApps) for persistent and censorship-resistant storage. This often involves client-side uploads and linking CIDs within smart contracts.
• Monitor Usage: Keep track of your storage and bandwidth usage through your Web3 Storage dashboard to ensure you stay within your free tier limits or manage your paid plan effectively.
• Explore Advanced Features: Investigate options like custom gateways, NFT.Storage integration for NFT metadata and asset storage, and the broader IPFS ecosystem. The main Web3 Storage documentation is a comprehensive resource.
• Error Handling: Implement robust error handling in your application to manage API rate limits, network issues, and invalid requests gracefully.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check API Token: Ensure your API token is correct and hasn't expired. Verify there are no leading or trailing spaces if copied manually. Regenerate the token if uncertain.
• Authorization Header: Confirm the Authorization: Bearer YOUR_API_TOKEN header is correctly formatted in your request. A common error is omitting "Bearer" or having incorrect capitalization.
• File Path/Source: For curl, ensure the file path (@/path/to/your/file.txt) is accurate and the file exists. For client libraries, verify that the File object or equivalent data structure is correctly constructed and contains valid content.
• Network Connectivity: Check your internet connection and ensure there are no firewall rules blocking outbound requests to api.web3.storage.
• Content Type for HTTP API: While --data-binary with curl often handles this implicitly, if you are manually setting headers, ensure the Content-Type header is appropriate for the data you are sending (e.g., application/octet-stream for binary data, text/plain for plain text).
• Missing Content: If the API returns an error indicating no content, double-check that your request body actually contains the file data.
• Rate Limits: If you are making many rapid requests, you might hit API rate limits. Review the Web3 Storage API reference on rate limits and implement exponential backoff if necessary.
• Review Error Messages: Pay close attention to the error messages returned by the API. They often provide specific clues about what went wrong. For example, a 401 Unauthorized typically points to an invalid API token.
• Consult Documentation: The Web3 Storage API reference details expected request formats and possible error codes.