# JavaScript client library reference

To use the JavaScript client library for Web3.Storage, you must first obtain a free API token.

The client library automatically packs your uploads into a content addressible archive (CAR) for uploading to the Web3.Storage service, which stores data as blocks prefixed with the content identifier (CID) derived from a cryptographic hash of the data. You can then use a file's CID to retrieve it.

This page covers the core functionality of the JavaScript client. See the JavaScript utility libraries page for some additional packages that may be useful when working with Web3.Storage.

Minimum requirements

While we recommend that you install the latest stable version of the following software, you must have at least:

# Constructor

The constructor for Web3.Storage is simple; all you need is your API token.

import { Web3Storage } from 'web3.storage'

// Construct with token and endpoint
const client = new Web3Storage({ token: apiToken })

# Store files

Store files using the put() method.

# Usage

<clientObject>.put(file[], { options })

# Examples

    # Return value

    The method returns a string containing the CID of the uploaded CAR.

    # Parameters

    Method parameters are supplied in positional order.

    Number Type Description
    1 file[] An iterable collection of Files (opens new window) to be packed into a CAR and uploaded.
    2 {options} Optional. An object whose properties define certain Web3.Storage options and metadata about the files being uploaded. See below for more details.

    An {options} object has the following properties that can be used as parameters when calling put():

    name

    String. The name parameter lets you attach an arbitrary name to the uploaded content archive, which you can use to identify and organize your uploads. The name is not stored alongside the data on IPFS, but it is viewable within the file listing on the Web3.Storage site.

    const cid = await client.put(files, { name: 'cat pics' })
    
    maxRetries

    Number. You can specify how many times put should attempt to retry in case of failure by passing in a maxRetries option:

    const cid = await client.put(files, { maxRetries: 3 })
    
    wrapWithDirectory

    Boolean. The wrapWithDirectory parameter controls whether the files will be wrapped in an IPFS directory when added to Web3.Storage. With the default value of true, all files provided to the put method will be wrapped in an IPFS directory listing.

    For example, when adding a file called hello.txt using the default behavior, the root CID returned by the put method identifies a directory containing a file named hello.txt, rather than the hello.txt file itself, which is accessible at <rootCID>/hello.txt.

    If you are adding a directory full of files using the put method, you may want to override the default behavior to avoid an extra level of nesting in your IPFS path. For example, if you have a files directory like this:

    files
    ├── hello.txt
    └── stuff
        └── things.md
    

    Using the default behavior, the put method would return a CID for a directory containing a files subdirectory, like this:

    bafybeigw6rik2dlxlfx354ofycpjzljon7zagjofcb35csrsdujf3zbfca/
    └── files
        ├── hello.txt
        └── stuff
            └── things.md
    

    However, if you do this instead:

    const cid = await client.put(files, { wrapWithDirectory: false })
    

    The contents of the files directory will be at the top level, instead of the files directory itself:

    bafybeiebez7epbidb7f6fcurnd5ukpokrpq5wkrsuakynukpxxo4y4ewvi/
    ├── hello.txt
    └── stuff
        └── things.md
    
    onRootCidReady

    Function. Because the data is formatted for IPFS and Filecoin on the client, the root CID for the data is generated before the data is uploaded to Web3.Storage. If you want to display the CID to the user before the upload is complete, pass in an onRootCidReady function that accepts a CID string:

    const onRootCidReady = rootCid => console.log('root cid:', rootCid)
    const cid = await client.put(files, { onRootCidReady })
    
    onStoredChunk

    Function. You can also display progress updates by passing in an onStoredChunk callback. This is called after each chunk of data is uploaded, with the size of the chunk in bytes passed in as a parameter:

    const onStoredChunk = chunkSize => console.log(`stored chunk of ${chunkSize} bytes`)
    const cid = await client.put(files, { onStoredChunk })
    

    # Retrieve files

    Retrieve files using the get() method. You will need the CID you obtained at upload time that references the CAR for your uploaded files.

    # Usage

    <clientObject>.get(<CID>)
    

    # Example

    const res = await client.get(rootCid) // Web3Response
    const files = await res.files() // Web3File[]
    for (const file of files) {
      console.log(`${file.cid} ${file.name} ${file.size}`)
    }
    

    # Return value

    Returns undefined if there are no matches for the given CID.

    If found, the method returns a Web3Response object, which extends the Fetch API response object (opens new window) to add two iterator methods unique to the Web3.Storage client library: files() and unixFsIterator().

      # Parameters

      Parameters are supplied in positional order.

      Number Type Description
      1 string A string containing the CID of the CAR to be retrieved.

      # Check status

      Retrieve metadata about your file by using the status() method and supplying the CID of the file you are interested in. This metadata includes the creation date and file size, as well as details about how the network is storing your data. Using this information, you can identify peers on the IPFS (InterPlanetary File System) (opens new window) network that are pinning the data, and Filecoin (opens new window) storage providers that have accepted deals to store the data.

      # Usage

      <clientObject>.status(<CID>)
      

      # Examples

        # Parameters

        Parameters are supplied in positional order.

        Number Type Description
        1 string A string containing the CID of the CAR.

        # Return value

        Returns undefined if there are no matches for the given CID.

        If found, the status() method returns a {Status} object that contains the metadata for your object's storage deal on the Web3.Storage network, with the following properties:

        cid

        String. The cid property is the content identifier of the data for which you are retrieving status information.

        dagSize

        Number. The dagSize property is the total size, in bytes, of the Merkle Directed Acyclic Graph (DAG) (opens new window) containing the queried CID.

        created

        String. The created property gives the creation date in ISO 8601 (opens new window) format.

        TIP

        The created date returned by a call to status() is the date and time that the CID was first seen on the network. The date given by a call to list() is the date and time of a particular upload via a call to put(). These can differ if multiple users upload the same file(s).

        pins

        Array. The pins property is an array of Pin objects. Each Pin object represents a specific peer in the IPFS network, (opens new window) with the following structure:

        Pin {
          peerId: string, // Libp2p peer ID of the node pinning the data.
          peerName: string, // Human readable name for the peer pinning the data.
          region: string, // Approximate geographical region of the node pinning the data.
          status: string, // Can be one of: 'Pinned' | 'Pinning' | 'PinQueued'
          updated: string // Updated date in ISO 8601 format.
        }
        
        deals

        Array. The deals property is an array of Deal objects. Each Deal object represents a specific storage deal on the Filecoin network, (opens new window) for a specific Piece (opens new window) of data, with the following structure:

        Deal {
          dealId: number, // On-chain ID of the deal.
          storageProvider: string, // Address of the storage provider storing this data.
          status: string, // Can be one of: 'Queued' | 'Published' | 'Active'
          pieceCid: string, // Piece CID of the data in the deal.
          dataCid: string, // CID of the data aggregated in this deal.
          dataModelSelector: string, // Selector for extracting data from the aggregated root.
          activation: string, // Date when the deal will become active, in ISO 8601 format.
          created: string, // Creation date, in ISO 8601 format.
          updated: string // Updated date, in ISO 8601 format.
        }
        

        # List uploads

        List previous uploads with the list() method.

        # Usage

        <clientObject>.list({before, maxResults})
        

        # Example

        The following example stores return values from a call to list() into a JavaScript array:

        // Return the names of 10 uploads
        const uploadNames = []
        for await (const item of client.list({ maxResults: 10 })) {
            uploadNames.push(item.name)
        }
        

        # Parameters

        The list() method accepts an {options} object with the following properties:

        before

        String. Specifies a date, in ISO 8601 format. Ensures that the call to list() will not return any results newer than the given date.

        maxResults

        Number. Specifies the maximum number of uploads to return when calling list().

        # Return value

        The return value for list() is an AsyncIterable object, containing objects whose data structure is the same as the return value for status() but with one extra propery: a string field called name that corresponds to the value given passed to the name parameter in the original call to put(). This means that iterating through results from your call to list() yields objects with the below example structure.

        {
          "name": "cat pics",
          "cid": "bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e",
          "created": "2021-07-14T19:27:14.934572Z",
          "dagSize": 101,
          "pins": [{
            "peerId": "12D3KooWR1Js",
            "peerName": "peerName",
            "region": "peerRegion",
            "status": "Pinned"
          }],
          "deals": [{
            "dealId": 12345,
            "storageProvider": "f099",
            "status": "Active",
            "pieceCid": "bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e",
            "dataCid": "bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e",
            "dataModelSelector": "Links/0/Links",
            "activation": "2021-07-14T19:27:14.934572Z",
            "created": "2021-07-14T19:27:14.934572Z",
            "updated": "2021-07-14T19:27:14.934572Z"
          }]
        }
        

        TIP

        The created date on these objects are the date and time that the user uploaded via put(). The created date given by a call to status() is the date and time that the CID was first seen on the network. These can differ if multiple users uploaded the same file(s).

        # Store CAR files

        Store a CAR file (opens new window) using the putCar() method.

        # Usage

        <clientObject>.putCar(car, { options })
        

        # Examples

        import fs from 'fs'
        import { Readable } from 'stream'
        import { CarReader, CarWriter } from '@ipld/car'
        import * as raw from 'multiformats/codecs/raw'
        import { CID } from 'multiformats/cid'
        import { sha256 } from 'multiformats/hashes/sha2'
        
        async function getCar() {
          const bytes = new TextEncoder().encode('random meaningless bytes')
          const hash = await sha256.digest(raw.encode(bytes))
          const cid = CID.create(1, raw.code, hash)
          // create the writer and set the header with a single root
          const { writer, out } = await CarWriter.create([cid])
          Readable.from(out).pipe(fs.createWriteStream('example.car'))
          // store a new block, creates a new file entry in the CAR archive
          await writer.put({ cid, bytes })
          await writer.close()
          const inStream = fs.createReadStream('example.car')
          // read and parse the entire stream in one go, this will cache the contents of
          // the car in memory so is not suitable for large files.
          const reader = await CarReader.fromIterable(inStream)
          return reader
        }
        
        const car = await getCar()
        const cid = await client.putCar(car)
        

        # Return value

        The method returns a string containing the CID of the uploaded CAR.

        # Parameters

        Method parameters are supplied in positional order.

        Number Type Description
        1 car The CAR file to be uploaded.
        2 {options} Optional. An object whose properties define certain Web3.Storage options and metadata about the files being uploaded. See below for more details.

        An {options} object has the following properties that can be used as parameters when calling putCar():

        name

        String. The name parameter lets you attach an arbitrary name to the uploaded content archive, which you can use to identify and organize your uploads. The name is not stored alongside the data on IPFS, but it is viewable within the file listing on the Web3.Storage site.

        const cid = await client.putCar(files, { name: 'cat pics' })
        
        maxRetries

        Number. You can specify how many times putCar should attempt to retry in case of failure by passing in a maxRetries option. The default value is 5.

        const cid = await client.putCar(files, { maxRetries: 3 })
        
        onStoredChunk

        Function. You can also display progress updates by passing in an onStoredChunk callback. This is called after each chunk of data is uploaded, with the size of the chunk in bytes passed in as a parameter. By default, data is split into chunks of around 10MB.

        const onStoredChunk = chunkSize => console.log(`stored chunk of ${chunkSize} bytes`)
        const cid = await client.putCar(car, { onStoredChunk })
        
        decoders

        BlockDecoder (opens new window). Used to specify additional IPLD block decoders which interpret the data in the CAR file and split it into multiple chunks. Note these are only required if the CAR file was not encoded using the default encoders: dag-pb, dag-cbor and raw.

        import { Web3Storage } from 'web3.storage'
        import { CarReader, CarWriter } from '@ipld/car'
        import { encode } from 'multiformats/block'
        import * as json from '@ipld/dag-json'
        import { sha256 } from 'multiformats/hashes/sha2'
        
        async function storeDagJSON(jsonObject) {
          // encode the json object into an IPLD block
          const block = await encode({ value: jsonObject, codec: json, hasher: sha256 })
        
          // create a new CarWriter, with the encoded block as the root
          const { writer, out } = CarWriter.create([block.cid])
        
          // add the block to the CAR and close it
          writer.put(block)
          writer.close()
        
          // create a new CarReader we can hand to Web3.Storage.putCar
          const reader = await CarReader.fromIterable(out)
        
          // upload to Web3.Storage using putCar
          console.log('uploading car.')
          const client = new Web3Storage({ token: process.env.WEB3STORAGE_TOKEN })
          const cid = await client.putCar(reader, {
            name: 'putCar using dag-json',
        
            // include the dag-json codec in the decoders field
            decoders: [json]
          })
          console.log('Stored dag-json data! CID:', cid)
        }
        
        storeDagJSON({
          hello: 'world'
        })