📁 File

Any kind of file can be uploaded to Lighthouse. Refer to the code example given below. For developers building on other programming languages use the API directly.

info

Lighthouse currently allows a maximum file size of 24GB to be uploaded in a single request.

JS SDK

Method 1: NodeJS:

import lighthouse from '@lighthouse-web3/sdk'

/**
 * This function allows you to upload a file or a folder to Lighthouse.
 * 
 * @param {string} path - The location of your file or folder.
 * @param {string} apiKey - Your personal API key for Lighthouse.
 * @param {object} options - Optional configuration (cidVersion, onProgress, headers).
 * @return {object} - Returns details about the uploaded file.
*/
const uploadResponse = await lighthouse.upload(
  '/home/cosmos/Desktop/wow.jpg', 
  'YOUR_API_KEY_HERE'
)

console.log(uploadResponse)

/*Sample response
{
  data: {
    Name: 'wow.jpg',
    Hash: 'QmUHDKv3NNL1mrg4NTW4WwJqetzwZbGNitdjr2G6Z5Xe6s',
    Size: '31735'
  }
}
*/

With Options (Progress Tracking & Storage Type):

import lighthouse from '@lighthouse-web3/sdk'

const uploadWithOptions = async () => {
  const response = await lighthouse.upload(
    '/home/cosmos/Desktop/wow.jpg',
    'YOUR_API_KEY_HERE',
    {
      cidVersion: 1,
      onProgress: (progressData) => {
        console.log(`Upload Progress: ${progressData.progress}%`)
      },
      headers: {
        storageType: 'lifetime'  // Storage plan: "annual" or "lifetime"
      }
    }
  )
  
  console.log('File uploaded:', response.data.Hash)
}

Backward Compatibility

The old positional parameter signature still works: upload(path, apiKey, cidVersion, progressCallback)

Method 2: Browser

import React from "react"
import lighthouse from '@lighthouse-web3/sdk'

function App() {

  const uploadFile = async (file) => {
    // Push file to lighthouse node
    // Both file and folder are supported by upload function
    const output = await lighthouse.upload(
      file, 
      "YOUR_API_KEY",
      {
        onProgress: (progressData) => {
          console.log(`Upload Progress: ${progressData.progress}%`)
        },
        headers: {
          storageType: 'lifetime'  // Storage plan: "annual" or "lifetime"
        }
      }
    )
    
    console.log('File Status:', output)
    /*
      output:
        data: {
          Name: "filename.txt",
          Size: 88000,
          Hash: "QmWNmn2gr4ZihNPqaC5oTeePsHvFtkWNpjY3cD6Fd5am1w"
        }
      Note: Hash in response is CID.
    */

      console.log('Visit at https://gateway.lighthouse.storage/ipfs/' + output.data.Hash)
  }

  return (
    <div className="App">
      <input onChange={e=>uploadFile(e.target.files)} type="file" />
    </div>
  )
}

export default App

API

curl -X POST -H 'Authorization: Bearer API_KEY' -F 'file=@/mnt/c/Users/ravis/Desktop/unnamed.jpeg' 'https://upload.lighthouse.storage/api/v0/add'

CLI

The given command can be used to upload a file or directory on Lighthouse:

lighthouse-web3 upload <path>

Python SDK

from lighthouseweb3 import Lighthouse

# Initialize Lighthouse with your API token
lh = Lighthouse(token="YOUR_API_KEY")

# Upload a file
source_file_path = "/path/to/your/file.jpg"
upload_response = lh.upload(source=source_file_path)

print(upload_response)
# Sample response
# {
#   'data': {
#     'Name': 'wow.jpg',
#     'Hash': 'QmUHDKv3NNL1mrg4NTW4WwJqetzwZbGNitdjr2G6Z5Xe6s',
#     'Size': '31735'
#   }
# }

print(f"File uploaded successfully!")
print(f"CID: {upload_response['data']['Hash']}")
print(f"Name: {upload_response['data']['Name']}")
print(f"Size: {upload_response['data']['Size']} bytes")
print(f"Visit at https://gateway.lighthouse.storage/ipfs/{upload_response['data']['Hash']}")

# Upload a file with a tag
tag = "my-tag"
upload_with_tag = lh.upload(source=source_file_path, tag=tag)
print(f"File uploaded with tag: {tag}")

# Upload a directory
directory_path = "/path/to/your/directory"
upload_dir = lh.upload(source=directory_path)
print(f"Directory uploaded! Root CID: {upload_dir['data']['Hash']}")

# Upload from a file-like object (BufferedReader)
import io
with open(source_file_path, 'rb') as file_obj:
    upload_blob = lh.uploadBlob(file_obj, "filename.jpg")
    print(f"Blob uploaded! CID: {upload_blob['data']['Hash']}")

Go SDK

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/lighthouse-web3/lighthouse-go-sdk/lighthouse"
)

func main() {
    client := lighthouse.NewClient(nil,
        lighthouse.WithAPIKey(os.Getenv("LIGHTHOUSE_API_KEY")),
    )

    ctx := context.Background()

    // Upload a file
    upload, err := client.Storage().UploadFile(ctx, "/path/to/your/file.jpg")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("File uploaded successfully!\n")
    fmt.Printf("CID: %s\n", upload.Hash)
    fmt.Printf("Name: %s\n", upload.Name)
    fmt.Printf("Size: %s\n", upload.Size)
}