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' });

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 });

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

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 });

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 });

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

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

String. The created property gives the creation date in ISO 8601 format.

Array. The pins property is an array of Pin objects. Each Pin object represents a specific peer in the IPFS network, 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.
}

Array. The deals property is an array of Deal objects. Each Deal object represents a specific storage deal on the Filecoin network, for a specific Piece 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.
}

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

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

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' });

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 });

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 });

BlockDecoder. 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'
})