Better storage.
Better transfers.
Better internet.

When you need file storage for your project, website, or application, Web3.Storage is here for you. All it takes to get started storing on the decentralized web is a free API token — no need to wrestle with complicated details.

In the past, storing data on the decentralized web wasn't always easy — but that's where Web3.Storage comes in. Most data on the internet today is hosted by massive storage providers like Amazon, Google, and Microsoft. This makes it simpler for developers to store application data, but big corporate platforms like these create silos by locking developers and users alike into walled gardens of services. What's more, as the market continues to consolidate, a small oligopoly of providers are essentially becoming the storage backbone of the internet.

One solution to this problem is using decentralized storage instead of big, corporate platforms to store data for apps and services. However, decentralized storage can be difficult to manage and add extra time and effort to an already crowded developer workflow — for example, most decentralized storage services need you to compile your data into a specific format, find a storage provider to host your data, buy some cryptocurrency to pay the storage provider, and then send your data across the internet. This is where Web3.Storage comes in.

With Web3.Storage, you get all the benefits of decentralized storage technologies with the frictionless experience you expect in a modern dev workflow. All you need to use Web3.Storage is an API token and your data. Under the hood, Web3.Storage is backed by the provable storage of Filecoin and makes data accessible to your users over the public IPFS network — but when it comes down to building your next application, service, or website, all you need to know is that Web3.Storage makes building on decentralized technologies simple.

Quickstart

Ready to get started using Web3.Storage right now? Get up and running in minutes by following this quickstart guide. In this guide, we'll walk through the following steps:

  1. Creating a Web3.Storage account.
  2. Getting a free API token.
  3. Creating and running a simple script to upload a file.
  4. Getting your uploaded file using your browser or curl.

This guide uses Node.js since it's the fastest way to get started using the Web3.Storage JavaScript client programmatically, but don't worry if Node isn't your favorite runtime environment — or if you'd rather not do any coding at all. You can also use Web3.Storage in the following ways:

PREREQUISITES

You'll need Node version 14 or higher and NPM version 7 or higher to complete this guide. Check your local versions like this:

node --version && npm --version
> v16.4.2
> 7.18.1

Create an account

You need a Web3.Storage account to get your API token and manage your stored data. You can sign up for free using your email address or GitHub.

Sign up using email
  1. Go to web3.storage/login to get started.
  2. Enter your email address.
  3. Check your inbox for a verification email from Web3.Storage, and click the Log in button in the email.
  4. You're all set!

Now that you're signed up and logged in, it's time to get your API token. ↓

Get an API token

It only takes a few moments to get a free API token from Web3.Storage. This token enables you to interact with the Web3.Storage service without using the main website, enabling you to incorporate files stored using Web3.Storage directly into your applications and services.

  1. Hover over Account and click Create an API Token in the dropdown menu to go to your Web3.Storage API Tokens page.
  2. Enter a descriptive name for your API token and click Create.
  3. Make a note of the Token field somewhere secure where you know you won't lose it. You can click Copy to copy your new API token to your clipboard.
Keep your API token private

Do not share your API token with anyone else. This key is specific to your account.

Now that you have your new API token, it's time to use a simple script to upload a file to Web3.Storage. ↓

Create the upload script

You can use the Web3.Storage site to upload files, but it's also quick and easy to create and run a simple upload script — making it especially convenient to add large numbers of files. This script contains logic to upload a file to Web3.Storage and get a content identifier (CID) back in return.

CAUTION

All data uploaded to Web3.Storage is available to anyone who requests it using the correct CID. Do not store any private or sensitive information in an unencrypted form using Web3.Storage.

  1. Create a folder for this quickstart project, and move into that folder:

    mkdir web3-storage-quickstart
    cd web3-storage-quickstart
    
  2. Create a file called put-files.js and paste in the following code:

    import process from 'process'
    import minimist from 'minimist'
    import { Web3Storage, getFilesFromPath } from 'web3.storage'
    
    async function main () {
      const args = minimist(process.argv.slice(2))
      const token = args.token
    
      if (!token) {
        return console.error('A token is needed. You can create one on https://web3.storage')
      }
    
      if (args._.length < 1) {
        return console.error('Please supply the path to a file or directory')
      }
    
      const storage = new Web3Storage({ token })
      const files = []
    
      for (const path of args._) {
        const pathFiles = await getFilesFromPath(path)
        files.push(...pathFiles)
      }
    
      console.log(`Uploading ${files.length} files`)
      const cid = await storage.put(files)
      console.log('Content added with CID:', cid)
    }
    
    main()
    
  3. Create another file called package.json and paste in the following code:

    {
        "name": "web3-storage-quickstart",
        "version": "0.0.0",
        "private": true,
        "description": "Get started using web3.storage in Node.js",
        "type": "module",
        "scripts": {
            "test": "echo \"Error: no test specified\" && exit 1"
        },
        "dependencies": {
            "minimist": "^1.2.5",
            "web3.storage": "^3.1.0"
        },
        "author": "YOUR NAME",
        "license": "(Apache-2.0 AND MIT)"
    }
    
  4. Save both files, and then run npm install from your project folder:

    npm install
    

    This step may take a few moments. Once it's done, the command should output something like this:

    added 224 packages, and audited 225 packages in 14s
    
    40 packages are looking for funding
     run `npm fund` for details
    
    found 0 vulnerabilities
    

Your script is good to go! Next, we'll run the script to upload a file. ↓

Run the script

Now that you've got your script ready to go, you just need to run it in your terminal window using node.

  1. Run the script by calling node put-files.js, using --token to supply your API token and specifying the path and name of the file you want to upload. If you'd like to upload more than one file at a time, simply specify their paths/names one after the other in a single command. Here's how that looks in template form:

    node put-files.js --token=<YOUR_TOKEN> ~/filename1 ~/filename2 ~/filenameN
    

    Once you've filled in your details, your command should look something like this:

    node put-files.js --token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6ZXRocjoweGZFYTRhODlFNUVhRjY5YWI4QUZlZUU3MUE5OTgwQjFGQ2REZGQzNzIiLCJpc3MiOiJ3ZWIzLXN0b3JhZ2UiLCJpYXQiOjE2MjY5Njk3OTY1NTQsIm5hbWUiOiJib25maXJlIn0.0S9Ua2FWEAZSwaemy92N7bW8ancRUtu4XtLS3Gy1ouA ~/hello.txt
    
Multiple files

You can upload a whole directory full of files at once by giving the script the path to a local directory. You can also upload multiple files by passing in more than one file path when you run the script.

  1. The command will output a CID:

    Content added with CID: bafybeig7sgl52pc6ihypxhk2yy7gcllu4flxgfwygp7klb5xdjdrm7onse
    
  2. Make a note of the CID, which looks like bafyb.... You'll need it in order to get your file.

Get the status of your upload

It's possible to get a variety of details about your upload, including its CID, upload date, size on the network, and info on IPFS pinning and Filecoin storage deals, by using the status() method within the JavaScript client library. Check out the Query how-to guide for more information.

Next up, we'll go over two methods for you to retrieve your data from Web3.Storage ↓

Get your file

You've already done the most difficult work in this guide — getting your files from Web3.Storage is simple.

  1. Go to https://dweb.link/ipfs/YOUR_CID, replacing YOUR_CID with the CID you noted in the last step.
  2. You should see a link to your file. If you uploaded multiple files at once, you'll see a list of all the files you uploaded.
  3. Click on a file's link to view it in your browser!

Finding your files again

If you ever need to find your files again, and you've forgotten the CID, head over to the Files table in Web3.Storage:

A listing of files in Web3.Storage

Next steps

Congratulations! You've just covered the basics of Web3.Storage. To learn more, take a look at these useful resources:

Was this information helpful?

Help us improve this site!